Calendly logoCalendly logo
Developer

Getting started with the Calendly API

Authenticate with personal access tokens or OAuth 2.0 to access Calendly data

The Calendly API v2 is REST-based and has predictable resource-oriented URLs. It uses JSON for request and response bodies and standard HTTP methods, authentication, and response codes. To access Calendly data, you can authenticate with personal access tokens or OAuth 2.0.

When to use personal access tokens to authenticate

When you need to securely share data from your or your company’s Calendly account with an internal or private application that’s not for use by others outside of your company, use personal access tokens.

A few examples where we recommend using personal access tokens include:

  • Testing out Calendly’s API endpoints

  • Building a reporting dashboard to reflect meetings your company has scheduled

  • Pushing Calendly event and invitee data into your company’s CRM

Personal access token permissions

A personal access token’s permissions change based on the role of the member (user, admin, owner) in the Calendly organization who generated it. Members of the Calendly organization who are users can only access their own personal Calendly account data.

If you need access to all Calendly account data across the Calendly organization, then use a personal access token generated by a member who is an admin or owner. To find out who in your Calendly organization has owner or admin permission, visit your Users Page.

Personal access token security

To keep your personal access tokens secure, we do not display or store them in your Calendly account and they’re unretrievable after they’re generated.

When to use OAuth 2.0 to authenticate

When you need to provide a way for Calendly members to securely share their Calendly account data with a public application you’ve built, use OAuth 2.0.

A few example scenarios where we recommend using OAuth 2.0 include when you’re building:

  • An application that allows your customers to get easy access to their Calendly event type links to share as they respond to support tickets

  • An application that creates an agenda each time your customer’s clients schedule a meeting with them

  • An application that contacts your customer’s Calendly invitees

OAuth 2.0 requirements

Before you can authenticate with OAuth 2.0, you’ll need:

  • The name of your application (cannot include the word “Calendly”)

  • Your OAuth redirect URI

    • This must be HTTPS for web applications unless the URI host is localhost.

    • For mobile or native applications use a specific redirect_uri, a Proof Key for Code Exchange (PKCE), and S256 for code_challenge_method. For more information on native and mobile authentication, see this guide.

  • A Client ID and Client Secret

    • When you register to authenticate with OAuth 2.0, we return to you a Client ID and Client Secret for your application to authenticate with the Calendly API.

Before you start

Here’s a summary:

  • You must be on a paid Premium or Pro subscription to subscribe to webhooks.

  • Your level of access to the Calendly API is determined by your user role in Calendly, so some HTTP methods, including those that access organization-wide Calendly data, may not be available to users because of insufficient user privileges.

  • Personal access tokens are unique and not meant to be shared with public sources or reused across applications.

  • OAuth 2.0 requires that you register your application so you can receive a Client ID and Client Secret to authenticate the application and start receiving Calendly account data.

    • Your request to register your application will be processed within one business day. You’ll receive an email when it’s complete or if there are follow-up questions.

How to authenticate with personal access tokens

To authenticate with personal access tokens:

  1. Log in to your Calendly account

  2. Go to the Integrations Page

  3. Select the API & Webhooks tile

  4. If you have no prior personal access tokens, select Get a token now under Personal Access Tokens.

  5. If you already have a token, select Generate new token under Your personal access tokens.

  6. At Create your personal access token, create an identifiable name for your token and select Create Token, then Copy token.

  7. If you need new personal access tokens, select Generate new token on your API & Webhooks page and repeat steps 5-7 as desired.

How to authenticate with OAuth 2.0

  1. Log in to your LastPass account and generate Sharing Keys.

    • You’ll receive your Client ID and Client Secret with your LastPass account.

  2. To register your public application, complete this form.

  3. After your register, you’ll receive your Client ID and Client Secret:

    • Make a GET request to retrieve the OAuth authorization code (see details). This call will need to be made in your web browser.

    • Make a POST request to retrieve the OAuth token (see details).

    • To test the OAuth token, make a call to the Users endpoint.

Book from your website with Calendly

To add Calendly to your website for bookings, you do not need to use authentication methods. Instead, embed Calendly on your website using one of the options in this article.

For questions about adding Calendly to your website, contact support+developer@calendly.com.