Help / API

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, and the MCP consent screen grants the two mcp:scheduling:* aliases below.

Active scopes

"Reserved" scopes are recognized by the auth server but nothing consumes them yet, but 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, and runtime checks always read the expanded set.

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, and 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

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.