Skip to main content

Authorization

Follow this guide to create a new Calendly credential that will allow Nexla to authenticate to and exchange data with your Calendly account.
calendly_api_auth.png

Calendly

Prerequisites​

The Calendly v2 REST API authenticates with a Bearer token in the Authorization header. Nexla uses a Calendly personal access token for this, which is the recommended method for service-to-service integrations where a Nexla data flow connects on behalf of your own organization rather than on behalf of an interactive third-party Calendly user.

In addition to the token, the Nexla credential requires your Calendly Organization URI. This URI scopes most read endpoints (event types, scheduled events, organization memberships, groups, routing forms, activity log, and webhook subscriptions) to your organization. The Calendly API uses URIs — full URLs that identify a resource — in place of opaque IDs for most relationships.

Important

Personal access tokens grant access to your Calendly data using your account's permissions. Store the token in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed. Webhook subscriptions and the Scheduling API require a paid Calendly plan (Standard, Teams, or Enterprise).

Generate a Personal Access Token​

The token must be generated from the Calendly account that has the access level required for your data flow. For organization-scoped endpoints (the majority of those listed in this connector), generate the token from an account with the Admin or Owner role on the organization.

  1. Sign in to the Calendly account that the Nexla integration will run as at calendly.com.

  2. Open the account menu in the upper-right corner, and click Integrations & apps.

  3. On the Integrations & apps page, select API and webhooks.

  4. In the Personal access tokens section, click Get a token now (or Generate new token if you already have one).

  5. Enter a descriptive name for the token (for example, "Nexla Integration"), and click Create token.

  6. Calendly will email a one-time authentication code to your account email address. Open the email, copy the code, and enter it in the verification prompt.

  7. When the token is displayed, click Copy token, and store the value in a secure secret manager. Calendly displays the full token value only once at generation time.

    Personal access tokens can be revoked from the same API and webhooks screen at any time. If a token is lost or compromised, revoke it and generate a new one.

For complete information about personal access tokens, see How to authenticate Calendly API with personal access tokens.

Find Your Organization URI​

The Organization URI is the full URL that identifies your Calendly organization — for example, https://api.calendly.com/organizations/AAAAAAAAAAAAAAAA. The simplest way to obtain it is to call the Get Current User endpoint with the token generated above.

  1. Run the following request, replacing <YOUR_PERSONAL_ACCESS_TOKEN> with the token value:

    curl --request GET \
      --url https://api.calendly.com/users/me \
      --header 'Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>'

  2. In the response, locate the resource.current_organization field. The value is your Organization URI. Copy this value for use in the Nexla credential.

    The resource.uri field in the same response is your user URI, which Calendly uses to scope webhook subscriptions at the user level. The resource.current_organization field is the Organization URI required by this credential.

For complete information about locating the organization URI, see How to find the organization or user URI.

Create a Calendly Credential​

  • To create a new Calendly credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Authentication Method​

  1. Enter your Calendly personal access token in the API Key field. This is the token value generated from Integrations & apps > API and webhooks > Personal access tokens in Calendly. Nexla sends this value as Authorization: Bearer <token> on every API call.

    The API Key field is masked after the credential is saved. To rotate the token, edit the credential and paste the new token value.

  2. Enter your Calendly Organization URI in the Organization URI field. This must be the full URI returned by the Get Current User endpoint as resource.current_organization — for example, https://api.calendly.com/organizations/AAAAAAAAAAAAAAAA. Most read endpoints and the user-invitation destination endpoint are scoped by this value.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.