Now Available: Scheduling API

Build scheduling directly into your app without redirects, iframes, or Calendly-hosted UI. Ideal for AI assistants, automation tools, and custom portals.Documentation available here.

Authorization Scopes

Overview

Authorization scopes define the permissions that an application requests when accessing Calendly APIs on behalf of a user. Scopes control which Calendly resources your integration can read or modify. When a user installs your app, the scopes you request determine what actions your app is permitted to perform.

Scopes follow these rules:

Read vs Write

Read scopes allow safe retrieval of data.
Write scopes allow creation, modification, or deletion of data.

Hierarchy

A :write scope implicitly includes the corresponding :read scope within the same domain.

Webhooks

Webhook subscriptions must be scoped by the event family you want to receive. Your app must be granted the related read scopes to receive webhook event payloads.

Scope Catalog

Category	Scope	Description	Provides access to
Scheduling	`availability:read`	Retrieve user and event-type availability.	`GET /user_busy_times` `GET /user_availability_schedules` `GET /user_availability_schedules/{uuid}` `GET /event_type_availability_schedules`
	`availability:write`	Update event type availability.	`PATCH /event_type_availability_schedules/{uuid}`
	`event_types:read`	Retrieve event type details and available times.	`GET /event_types, GET /event_types/{uuid}` `GET /event_type_available_times` `GET /event_type_memberships`
	`event_types:write`	Create or update event types.	`POST /event_types` `PATCH /event_types/{uuid}` `POST /one_off_event_types`
	`locations:read`	Retrieve configured meeting locations.	`GET /locations`
	`routing_forms:read`	Retrieve routing forms and submissions.	`GET /routing_forms` `GET /routing_forms/{uuid}` `GET /routing_form_submissions` `GET /routing_form_submissions/{uuid}`
	`shares:write`	Create and customize a single-use scheduling link from an existing event type.	`POST /shares`
	`scheduled_events:read`	Retrieve scheduled events and event invitee information.	`GET /scheduled_events` `GET /scheduled_events/{uuid}` `GET /scheduled_events/{uuid}/invitees` `GET /scheduled_events/{uuid}/invitees/{invitee_uuid}` `GET /invitee_no_shows/{uuid}`
	`scheduled_events:write`	Create event invitees, cancel events or mark invitees as no-show.	`POST /invitees` `POST /scheduled_events/{uuid}/cancellation` `POST /invitees/{uuid}/no_show` `DELETE /invitees/{uuid}/no_show`
	`scheduling_links:write`	Create a single-use scheduling link from an existing event type without any customization.	`POST /scheduling_links`
User management	`groups:read`	Retrieve group details and relationships.	`GET /groups` `GET /groups/{uuid}` `GET /group_relationships` `GET /group_relationships/{uuid}`
	`organizations:read`	Retrieve organization data, memberships, and invitations.	`GET /organizations/{uuid}` `GET /organization_memberships` `GET /organization_memberships/{uuid}` `GET /organization_invitations` `GET /organization_invitations/{uuid}`
	`organizations:write`	Invite or remove users from an organization.	`POST /organization_invitations` `DELETE /organization_invitations/{uuid}` `DELETE /organization_memberships/{uuid}`
	`users:read`	Retrieve user information.	`GET /users/{uuid}` `GET /users/me`
Webhooks	`webhooks:read`	Retrieve webhook subscriptions and sample payloads.	`GET /webhook_subscriptions` `GET /webhook_subscriptions/{uuid}` `GET /webhook_subscriptions/sample_data`
	`webhooks:write`	Create or delete webhook subscriptions.	`POST /webhook_subscriptions` `DELETE /webhook_subscriptions/{uuid}`
Security & Compliance	`activity_log:read`	View organization activity.	`GET /activity_log_entries`
	`data_compliance:write`	Delete invitee or event data.	`POST /data_compliance/deletion_event` `POST /data_compliance/invitee_deletion`
	`outgoing_communications:read`	Retrieve a list of outgoing SMS and email communications.	`GET /outgoing_communications`

Required Scopes Per Endpoint

Each API endpoint in the reference includes a “Required scopes” section that tells you which Auth scopes must be granted for the request to succeed. Example callout:

When a request is missing required scopes, the API returns an error indicating insufficient permissions.

Choosing Scopes

When your app initiates an OAuth flow, it should request the minimum set of scopes needed for your use cases. Overly broad scopes can lead to unnecessary user friction at install time. Review your integration’s features and map them to the scopes in the catalog above.

Example: Syncing basic scheduling data into a third party system

scheduled_events:read
Required to read scheduled meetings and their status.
invitees:read
Required to associate meetings with people and contact details.
webhooks:write (optional)
Recommended for near real time updates. Not required if the integration relies on polling.

Troubleshooting

Missing scope error
If you receive a 403 error indicating missing scopes:

Verify that the scopes requested during installation include all required by the endpoint you are calling.
Confirm that the user granted all requested scopes (users can decline scopes during install).
For existing installs, you may need to reauthorize the app to request additional scopes.

Webhooks not delivering events

Check that webhooks:write is granted.
Confirm that your subscription includes the event family you want to receive.
Ensure that the related domain read scopes are also granted.

Backward Compatibility

Legacy OAuth apps and Personal Access Tokens issued before the introduction of scoped permissions retain full access to available endpoints by default.

For newly created OAuth apps and new Personal Access Tokens, no API access is granted until scopes are explicitly requested and approved.

When a legacy token is refreshed, it is automatically migrated to the scoped token format. This migration happens transparently and does not require the user to reauthorize the application.

Sample Authorization URL

Replace CLIENT_ID and REDIRECT_URI with your values:

https://auth.calendly.com/oauth/authorize
?client_id=CLIENT_ID
&redirect_uri=REDIRECT_URI
&response_type=code
&scope=scheduled_events:read webhooks:write

List scopes separated by spaces. Only include the scopes your app needs.

Easyahead

Solutions

Resources

About