Scopes

Every API key carries a list of scopes. Without the right scope you get a 403:

{
  "error": {
    "code": "missing_scope",
    "message": "api key is missing required scope 'notes:write'",
    "details": {
      "required": ["notes:write"],
      "missing": ["notes:write"]
    }
  }
}

Convention

<module>:<verb>. Three verbs:

• read — every GET endpoint in that module
• write — POST / PUT / PATCH (creates and updates)
• admin — DELETE + role/share management + lock toggling

Catalog

Scope	What it covers
notes:read	Tree, detail, search
notes:write	Create + update; no root deletion
notes:admin	Delete folders, manage shares, lock toggling
sheets:read	Workbooks, tables, rows
sheets:write	Create tables and rows, edit cells
sheets:admin	Delete tables and columns
files:read	Browse and download
files:write	Upload and edit metadata
files:admin	Permanent delete (hard delete)
inbox:read	Inbox reads
inbox:send	Send email from connected accounts
workspaces:read	List + detail of workspaces
users:read	List users

Principle of least privilege

Mint a key with only what the AI / script actually needs. If an agent just reads notes, don't give it write. Keys without expiry can be revoked any time at Settings → Account → API keys.

God-mode (*)

There's a special scope * that bypasses every check. It's not exposed through the UI — only env-admin tooling (break-glass) can mint it. Regular users never get it.