API

Authenticate every request with a bearer token in the Authorization header. Tokens carry scopes that gate what each endpoint can do.

Authorization: Bearer <access-token>
Content-Type: application/json

Two kinds of token exist: workspace API keys (created by a workspace admin, and always starting with cxk_) and user-scoped OAuth access tokens (issued to an app acting on behalf of a signed-in user). A key belongs to the workspace, not to a person. Most endpoints act on a specific user (their profile, drafts, Drive, Calendar, Tasks, Contacts, Documents), so they need a user-scoped OAuth token and answer a workspace API key with 403 forbidden. A workspace API key can do four things today:

• Read the workspace and its storage, with workspace.read.
• Read mail with email.read, in the mailboxes the admin chose when creating the key: the mailbox list, threads, messages, attachments, labels, filters, addresses and search. Any other mailbox answers 404 not_found, as if it did not exist, and GET /v1/mailboxes lists only the key’s mailboxes.
• Change mail with email.write, in those same mailboxes: label and unlabel, archive, move, trash, mark as spam, snooze, mark read and flag, manage the mailbox’s labels and filters, and write drafts. A key cannot change a mailbox’s addresses; that answers 403 forbidden. Every change is recorded as the key’s, so the mail app’s activity feed names the key.
• Send mail with email.send: send or schedule a draft from one of those mailboxes. A key is no one, so its mail goes out in the mailbox owner’s name for that mailbox, as the web app would send it, and the workspace and mailbox sending limits apply.

The available scopes are:

Errors return a non-2xx status and a JSON body with a machine-readable error code and a human error_description. Some errors add extra fields (for example max_size). The API is rate limited to 600 requests per minute per token, and to 60 requests per minute per IP address for requests that carry no bearer token. A 429 carries Retry-After (in seconds) and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

{
  "error": "insufficient_scope",
  "error_description": "Required scope: drive.update"
}

Per-resource error codes (e.g. name_taken, file_too_large, sync_token_invalid) are documented alongside each endpoint.