Scopes & Permissions

Scopes follow the pattern resource:action and control what an API token or OAuth client can do. They are set at token creation or OAuth consent and cannot be expanded without re-issuing.

Wildcard: resource:* satisfies any action under that resource. *:* (superadmin only) bypasses all checks.

Drive

Scope	Grants
`drive:read`	Browse folders, download files, list shares, read versions, delta sync
`drive:write`	Upload files, create folders, rename, move, copy, share, trash, restore, delete
`drive:*`	Both read and write

Note: Drive endpoints require an acting user (OAuth user JWT or a PAT bound to a user_id). Pure service account tokens without a user context are rejected.

Sites

Scope	Grants
`sites:read`	List sites, read pages and page tree
`sites:write`	Create/update/delete sites and pages
`sites:*`	Both read and write

Sites also requires an acting user.

Calendar

Scope	Grants
`calendar:read`	Read calendars and events, free/busy queries
`calendar:write`	Create, update, delete events; import ICS

CalDAV endpoints use HTTP Basic or Bearer auth and enforce these scopes. REST calendar endpoints (/api/v1/calendar/*) are not yet in the hardened external surface — use CalDAV for external clients.

Contacts

Scope	Grants
`contacts:read`	List address books and contacts
`contacts:write`	Create, update, delete contacts

CardDAV is the recommended protocol for external contacts access.

Mail

Scope	Reserved — not enforced on any external endpoint in v1
`mail:read`	Read mailboxes and messages
`mail:send`	Send messages on behalf of a user

These scopes are defined for forward-compatibility. No external mail REST endpoints enforce them yet. Use IMAP/SMTP for external mail access today.

Partner / MSP

Scope	Grants
`partner:orgs:read`	List and inspect customer organisations
`partner:orgs:write`	Create and update organisations
`partner:orgs:manage`	Suspend and activate organisations
`partner:orgs:*`	All org operations
`partner:users:read`	List and inspect users within managed orgs
`partner:users:write`	Create and invite users
`partner:users:manage`	Suspend, activate, delete users; reset passwords
`partner:users:*`	All user operations
`partner:teams:read`	List teams and members
`partner:teams:write`	Create and update teams, add members
`partner:teams:manage`	Delete teams, remove members
`partner:teams:*`	All team operations
`partner:billing:read`	Read subscription and invoice state
`partner:plans:read`	List published plans
`partner:plans:write`	Change plan and seat count
`partner:plans:*`	Both plan operations

Partner API calls require the caller’s organisation to be a reseller (reseller_depth >= 1). These scopes are not available to regular org-level tokens.

Webhooks

Scope	Grants
`webhooks:manage`	Create, update, pause, delete webhook subscriptions and rotate secrets

In v1, webhook subscription management also accepts any token with admin:access permission (the first-party admin role).

Admin

Scope	Grants
`admin:read`	Read-only org admin data (users, roles, settings)
`admin:access`	Full org admin access — required for webhook management and service principal management

Scopes not in v1

Scope	Reason deferred
`chat:read` / `chat:write`	E2EE complexity — consent and key management unresolved
`mail:admin`	Full mail admin surface deferred
`admin:write`	Broad admin write deferred until partner model is proven at scale

Scope inheritance rules

*:* (superadmin) satisfies any scope check — never issue this to external clients.
A prefix wildcard like partner:orgs:* satisfies partner:orgs:read, partner:orgs:write, and partner:orgs:manage.
The effective scopes of a token are the intersection of: (a) the scopes granted on the token itself, and (b) the scopes allowed on the service principal. Granting a token a scope that the service principal doesn’t have has no effect.

Which actors get which scopes

Actor	Typical scopes
Personal connected app (user-delegated OAuth)	`drive:read`, `calendar:read`, `contacts:read` — user-level only
MSP / reseller service account	`partner:orgs:`, `partner:users:`, `partner:billing:read`
Org automation / CRM	`drive:read`, `calendar:read`, `contacts:read`
Org admin script	`admin:access`, `webhooks:manage`

See the full actor × auth method matrix for details on which auth flow each actor uses.