Scopes

Every endpoint declares a required scope. The bearer token must hold that scope or the request fails with 403 insufficient_scope and a WWW-Authenticate: Bearer error="insufficient_scope" scope="<scope>" header.

Scopes are granted when:

the user approves the OAuth consent screen for a third-party client,
the admin selects scopes when minting a PAT, or
the user connects an AI assistant — the MCP consent screen grants the two mcp:scheduling:* aliases below.

Active scopes

Scope	What it grants
`user:read`	Read the authenticated user's profile (`/v1/me`).
`users:read`	List and search organization members. (MCP only.)
`event_types:read`	List and read event types.
`event_types:create`	Create event types. (Reserved — no public write endpoints yet.)
`event_types:update`	Modify event types. (MCP only.)
`event_types:delete`	Delete event types. (Reserved.)
`slots:read`	Check slot availability.
`bookings:read`	List and read bookings.
`bookings:create`	Create bookings.
`bookings:cancel`	Cancel bookings.
`bookings:reschedule`	Reschedule bookings.
`bookings:update`	Patch booking metadata, responses, and attendee name.
`webhooks:read`	List and read webhook subscriptions, and their recent deliveries (`/v1/webhooks`).
`webhooks:write`	Create, edit, delete, rotate the secret of, and test webhooks.
`availability:read`	Read schedules. (MCP only.)
`availability:write`	Modify schedules. (MCP only.)
`meetings:read`	Read the host-side meetings view. (MCP only.)
`meetings:write`	Mark meetings as no-show. (MCP only.)
`contacts:read`	Search contacts and read meeting history. (MCP only.)
`single_use_links:read`	List single-use booking links. (MCP only.)
`single_use_links:write`	Generate and delete single-use booking links. (MCP only.)
`roundtables:read`	List and read roundtables (group scheduling polls). (MCP only.)
`roundtables:write`	Create and publish roundtables. (MCP only.)

"Reserved" scopes are recognized by the auth server but nothing consumes them yet — they exist so apps can request the right surface ahead of the endpoints landing. "MCP only" scopes are consumed by the MCP server's tools (the /mcp endpoint for AI assistants) — no /v1/* REST endpoint reads them yet.

Alias scopes

Some commonly-bundled scopes are exposed as aliases. When a token is granted with an alias, the alias is expanded at grant time into its constituent granular scopes — runtime checks always read the expanded set.

Alias	Expands to
`event_types:write`	`event_types:create`, `event_types:update`, `event_types:delete`
`bookings:write`	`bookings:create`, `bookings:cancel`, `bookings:reschedule`, `bookings:update`
`mcp:scheduling:read`	`user:read`, `event_types:read`, `slots:read`, `bookings:read`, `meetings:read`, `contacts:read`, `availability:read`, `single_use_links:read`, `roundtables:read`, `users:read`
`mcp:scheduling:write`	everything in `mcp:scheduling:read`, plus `event_types:update`, `bookings:create`, `bookings:cancel`, `bookings:reschedule`, `meetings:write`, `availability:write`, `single_use_links:write`, `roundtables:write`

The two mcp:scheduling:* aliases are what the AI-assistant consent screen grants. They are OAuth-only — they never appear in the PAT scope picker — and are only valid for tokens addressed to the MCP endpoint.

Practical consequence: a token granted bookings:write carries four granular scopes — that's the set you'll see in meta.request_id audit logs, in the /v1/_ping response, and in the scope claim of an issued OAuth token.

Reserved scopes (not yet active)

These appear in discovery but no endpoint currently consumes them:

routing_forms:read    routing_forms:create   routing_forms:update
routing_forms:delete  routing_forms:write    teams:read
teams:write           calendars:read         calendars:write
analytics:read

Required scope per endpoint

Method · Path	Scope
`GET /v1/_ping`	none (auth only)
`GET /v1/me`	`user:read`
`GET /v1/event-types`	`event_types:read`
`GET /v1/event-types/:idOrSlug`	`event_types:read`
`GET /v1/slots`	`slots:read`
`GET /v1/slots/check`	`slots:read`
`GET /v1/bookings`	`bookings:read`
`GET /v1/bookings/:uid`	`bookings:read`
`POST /v1/bookings`	`bookings:create`
`POST /v1/bookings/:uid/cancel`	`bookings:cancel`
`POST /v1/bookings/:uid/reschedule`	`bookings:reschedule`
`PATCH /v1/bookings/:uid`	`bookings:update`
`GET /v1/webhooks`	`webhooks:read`
`GET /v1/webhooks/:id`	`webhooks:read`
`GET /v1/webhooks/:id/deliveries`	`webhooks:read`
`POST /v1/webhooks`	`webhooks:write`
`PATCH /v1/webhooks/:id`	`webhooks:write`
`DELETE /v1/webhooks/:id`	`webhooks:write`
`POST /v1/webhooks/:id/rotate-secret`	`webhooks:write`
`POST /v1/webhooks/:id/test`	`webhooks:write`

Requesting scopes

OAuth: include them on /v1/oauth/authorize as a space-separated scope parameter. The set must be a subset of the client's registered allowed_scopes — otherwise 400 invalid_scope. The user can narrow further from the consent screen; granted scopes are the user's choice intersected with the request.

PAT: select scopes in the New API key dialog in Admin Center → API. Expanding the scope set on an existing key requires re-confirming your account password — narrowing does not.

Insufficient scope

{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the 'bookings:create' scope",
    "details": { "required_scope": "bookings:create" },
    "request_id": "req_…"
  }
}

The remedy is always: mint or re-authorize a token that holds the required scope. Scopes cannot be elevated mid-session.

Last updated July 29, 2026.

PreviousAuthentication Next Rate limits