OAuth

1. OAuth Client Credentials

You can create an OAuth client via the following page https://app.icalendly.com/settings/developer/oauth. The OAuth client will be in a "pending" state and not yet ready to use. You must select at least one scope when creating the OAuth client. You can register up to 10 redirect URIs per OAuth client.An admin from iCalendly will then review your OAuth client and you will receive an email if it was accepted or rejected. If it was accepted then your OAuth client is ready to be used.

Available Scopes

Scopes control which API endpoints the OAuth token can access. Once a user authorizes your client with a given set of scopes, the issued access token can only be used to call endpoints covered by those scopes — any request to an endpoint outside the granted scopes will be rejected. The following scopes are available:

Some endpoints like POST /v2/bookings (create), POST /v2/bookings/:bookingUid/cancel (cancel), POST /v2/bookings/:bookingUid/reschedule (reschedule), and slot availability endpoints are public and do not require any scope. You can still pass an OAuth access token when calling these endpoints — the token is accepted but not required. This means you can use a consistent Authorization: Bearer <token> header across all API requests without worrying about whether a specific endpoint is public or scoped.

2. Authorize

To initiate the OAuth flow, direct users to the following authorization URL:https://app.icalendly.com/auth/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_STATE&scope=BOOKING_READ%20BOOKING_WRITEURL Parameters:

After users click Allow, they will be redirected to the redirect_uri with code (authorization code) and state as URL parameters:

https://your-app.com/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE

Error Handling

Errors during the authorization step are displayed directly to the user on the iCalendly authorization page. Your application will not receive a JSON error response for these cases:

• Client not found: No OAuth client exists with the provided client_id.
• Client not approved: The OAuth client has not been approved by a iCalendly admin yet.
• Mismatched redirect URI: The redirect_uri does not match any of the registered redirect URIs for the OAuth client.

If an error occurs after the client is validated, the user is redirected to the redirect_uri with an error:

• Scope required: If the scope parameter is missing, the error scope parameter is required for this OAuth client is displayed on the authorization page.
• Unknown scope: If the scope parameter includes scope values that do not exist, the user is redirected with error=invalid_scope and error_description=Requested scope is not a recognized scope. This applies to both regular and legacy clients.
• Invalid scope: If the scope parameter includes scopes not enabled on the OAuth client, the user is redirected with error=invalid_request and error_description=Requested scope exceeds the client's registered scopes.
• Access denied: If the user denies access or has insufficient permissions, the user is redirected with an error.

https://your-app.com/callback?error=invalid_request&error_description=Requested+scope+exceeds+the+client%27s+registered+scopes&state=YOUR_STATE

3. Exchange Token

Exchange an authorization code for access and refresh tokens. The token endpoint also accepts application/x-www-form-urlencoded content type.Endpoint:POST https://app.icalendly.com/v2/auth/oauth2/token

3.1 Confidential Clients

Confidential clients authenticate with a client_secret. All parameters are required:

curl -X POST https://app.icalendly.com/v2/auth/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://your-app.com/callback"
  }'

3.2 Public Clients (PKCE)

Public clients (e.g. single-page apps, mobile apps) use PKCE instead of a client_secret. You must have sent a code_challenge during the authorization step. All parameters are required:

curl -X POST https://app.icalendly.com/v2/auth/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://your-app.com/callback",
    "code_verifier": "YOUR_CODE_VERIFIER"
  }'

Success Response (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800,
  "scope": "BOOKING_READ BOOKING_WRITE"
}

Access tokens expire after 30 minutes (expires_in: 1800). Use the refresh token to obtain a new access token. The scope field contains the granted scopes as a space-separated string.

Error Responses

Error responses include error and error_description fields.

Invalid or expired authorization code (400)

{
  "error": "invalid_grant",
  "error_description": "code_invalid_or_expired"
}

The authorization code has already been used, has expired, or is invalid. Request a new authorization code.

Invalid client credentials (401)

{
  "error": "invalid_client",
  "error_description": "invalid_client_credentials"
}

The client_secret does not match the client_id. Verify your credentials.

Client not found (401)

{
  "error": "invalid_client",
  "error_description": "client_not_found"
}

No OAuth client exists with the provided client_id.

Missing client_id (400)

{
  "error": "invalid_request",
  "error_description": "client_id is required"
}

The client_id field is missing from the request body.

Invalid grant_type (400)

{
  "error": "invalid_request",
  "error_description": "grant_type must be 'authorization_code' or 'refresh_token'"
}

The grant_type field must be either authorization_code or refresh_token.

4. Refresh Token

Refresh an expired access token using a refresh token.Endpoint:POST https://app.icalendly.com/v2/auth/oauth2/token

4.1 Confidential Clients

Confidential clients authenticate with a client_secret. All parameters are required:

curl -X POST https://app.icalendly.com/v2/auth/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

4.2 Public Clients

Public clients do not use a client_secret. All parameters are required:

curl -X POST https://app.icalendly.com/v2/auth/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Success Response (200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 1800,
  "scope": "BOOKING_READ BOOKING_WRITE"
}

Scopes are preserved from the original authorization. You do not need to re-request scopes when refreshing tokens.

Error Responses

Invalid refresh token (400)

{
  "error": "invalid_grant",
  "error_description": "invalid_refresh_token"
}

The refresh token is invalid, expired, or malformed. The user must re-authorize.

Invalid client credentials (401)

{
  "error": "invalid_client",
  "error_description": "invalid_client_credentials"
}

The client_secret does not match the client_id.

Client not found (401)

{
  "error": "invalid_client",
  "error_description": "client_not_found"
}

No OAuth client exists with the provided client_id.

5. Client Secret Rotation

iCalendly supports rotating client secrets with zero downtime. You can have up to 2 active secrets at a time, allowing you to deploy a new secret before revoking the old one.

Why rotate secrets?

• A secret may have been accidentally exposed or compromised
• Your security policy requires periodic credential rotation
• An employee with access to the secret has left your organization

How it works

1. Generate a new secret from your OAuth client settings. Your old secret continues to work — both secrets are valid simultaneously.
2. Update your application to use the new secret in all token exchange and refresh requests.
3. Verify that your application works correctly with the new secret.
4. Revoke the old secret from the settings page. Any requests using the old secret will immediately fail.

Important notes

• You can have a maximum of 2 secrets per client. To generate a new one when you already have 2, revoke an existing secret first.
• New secrets are shown only once when generated. Copy and store them securely.
• Revoking a secret takes effect immediately — there is no grace period.
• Existing access and refresh tokens remain valid after secret rotation. Rotation only affects token exchange and refresh requests that require client_secret.
• Secret rotation applies only to confidential clients. Public clients (PKCE) do not use client secrets.

What needs to change in your code

When you rotate a secret, update the client_secret parameter in these requests:

Legacy Client Migration

If your OAuth client was created before scopes were introduced, it is considered a legacy client. A client is treated as legacy if it has no scopes configured, or if it only has the old legacy scope values (READ_BOOKING and/or READ_PROFILE). Access tokens issued by legacy clients can access any resource on behalf of the authorizing user — scopes are not enforced.You can migrate a legacy client to use explicit scopes without creating a new client. Order matters — follow these steps to avoid breaking existing integrations:

Step 1: Update your authorization URL

Add a scope query parameter to your authorization URL before changing any client settings. Legacy clients skip scope validation during authorization, so users can already authorize with a scope parameter even while the client is still in legacy mode.

https://app.icalendly.com/auth/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=YOUR_STATE&scope=BOOKING_READ%20BOOKING_WRITE

New access tokens issued after this change will carry only the scopes you specified. For the full list of available scopes, see Available Scopes.

Step 2: Update client scopes in settings

Once your authorization URL is updated and you have verified that new tokens are being issued with the correct scopes, open your OAuth client settings and select the matching scopes. Save the client.After this step, the client is no longer treated as a legacy client. Scope validation is enforced for all new authorization requests.

Do not update the client scopes before updating your authorization URL. Doing so will immediately break the authorization flow for any user who visits the old URL without a scope parameter.

Existing tokens

Tokens issued before the migration continue to work until users re-authorize. There is no forced invalidation of existing tokens during the migration.

Re-approval

Changing properties below will trigger a re-review by iCalendly admins and set client to a "pending" state:

• Name
• Logo
• Website URL
• Redirect URI
• Scope expansion (adding new scopes that the client did not previously have)

While pending, the client can only be used by the client owner for testing — other users cannot authorize with it.Changing properties below will NOT trigger a re-review and client will remain in the state it is:

• Adding a _READ scope when the corresponding _WRITE scope is already granted (e.g. adding BOOKING_READ when BOOKING_WRITE is already present)
• Removing scopes
• Purpose description change
• Updating scopes on a legacy client, as long as only user-level scopes are added — adding TEAM_ or ORG_ scopes to a legacy client will trigger re-approval. See Legacy Client Migration for details.

6. Verify Access Token

To verify the correct setup and functionality of OAuth credentials, use the following endpoint:

Endpoint: GET https://app.icalendly.com/v2/me

curl -X GET https://app.icalendly.com/v2/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "cal-api-version: 2024-08-13"