Authentication

Authorization Scopes

Authorization scopes for Calendly API access

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

CategoryScopeDescriptionProvides access to
Schedulingavailability:readRetrieve user and event-type availability.GET /user_busy_times
GET /user_availability_schedules
GET /user_availability_schedules/{uuid}
GET /event_type_availability_schedules
availability:writeUpdate event type availability.PATCH /event_type_availability_schedules/{uuid}
event_types:readRetrieve event type details and available times.GET /event_types
GET /event_types/{uuid}
GET /event_type_available_times
GET /event_type_memberships
event_types:writeCreate or update event types.POST /event_types
PATCH /event_types/{uuid}
POST /one_off_event_types
locations:readRetrieve configured meeting locations.GET /locations
routing_forms:readRetrieve routing forms and submissions.GET /routing_forms
GET /routing_forms/{uuid}
GET /routing_form_submissions
GET /routing_form_submissions/{uuid}
shares:writeCreate and customize a single-use scheduling link from an existing event type.POST /shares
scheduled_events:readRetrieve 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:writeCreate 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:writeCreate a single-use scheduling link from an existing event type without any customization.POST /scheduling_links
User managementgroups:readRetrieve group details and relationships.GET /groups
GET /groups/{uuid}
GET /group_relationships
GET /group_relationships/{uuid}
organizations:readRetrieve organization data, memberships, and invitations.GET /organizations/{uuid}
GET /organization_memberships
GET /organization_memberships/{uuid}
GET /organization_invitations
GET /organization_invitations/{uuid}
organizations:writeInvite or remove users from an organization.POST /organization_invitations
DELETE /organization_invitations/{uuid}
DELETE /organization_memberships/{uuid}
users:readRetrieve user information.GET /users/{uuid}
GET /users/me
Webhookswebhooks:readRetrieve webhook subscriptions and sample payloads.GET /webhook_subscriptions
GET /webhook_subscriptions/{uuid}
GET /webhook_subscriptions/sample_data
webhooks:writeCreate or delete webhook subscriptions.POST /webhook_subscriptions
DELETE /webhook_subscriptions/{uuid}
Security & Complianceactivity_log:readView organization activity.GET /activity_log_entries
data_compliance:writeDelete invitee or event data.POST /data_compliance/deletion_event
POST /data_compliance/invitee_deletion
outgoing_communications:readRetrieve a list of outgoing SMS and email communications.GET /outgoing_communications
Contactscontacts:readRetrieve Contact details.GET /contacts
GET /contacts/{contact_uuid}
contacts:writeCreate, update, and delete Contacts.POST /contacts
PATCH /contacts/{contact_uuid}
DELETE /contacts/{contact_uuid}
Notetakermeeting_recaps:readRetrieve recap summaries, action items, discussions, and transcripts.GET /meeting_recaps
GET /meeting_recaps/{recap_uuid}
GET /meeting_recaps/{recap_uuid}/transcript
meeting_recaps:writeUpdate or delete meeting recaps.PATCH /meeting_recaps/{recap_uuid}
DELETE /meeting_recaps/{recap_uuid}

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:

Required scopes: scheduled_events:read

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, invitees, and their status.
  • 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:

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

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