Identity and access
Roles and scopes
Every permission is a scope; roles are fixed sets of scopes, and keys carry a subset of their creator's.
How permissions work
A scope is a permission such as projects:write. Every request is checked for the scope it needs, in the organization it acts on:
- People get the scopes of their role in each organization. They're worked out from the role in the access token, so a role change takes effect within 15 minutes.
- Keys carry the scopes chosen when they were created, at most the creator's own (Keys).
- Agents don't use scopes; what a device may do is decided when it's approved.
A request without the scope gets 403 with Missing scope <scope>.
Roles
| Role | Scopes |
|---|---|
| Owner | Every scope except the platform ones. Owners can also invite owners. |
| Admin | Same scopes as owners. |
| Developer | Every :read scope except audit:read, plus the developer writes marked in the table below. |
| Viewer | Every :read scope except audit:read, plus chat:use. |
In the platform organization, owners and admins also get the platform: scopes. A few decisions use the role itself rather than a scope: inviting members, creating and deleting teams, and creating and revoking keys need an owner or admin.
Scopes
Generated from the platform's scope list. Checked by lists the API routes and MCP tools that require each scope; "Not checked yet" means a role grants it but nothing requires it today.
| Scope | Covers | Owner | Admin | Developer | Viewer | Checked by |
|---|---|---|---|---|---|---|
platform:admin | Organizations, plans, platform stats and the platform audit log. | Platform org | Platform org | 10 API routes | ||
platform:infra | The region and location registry. | Platform org | Platform org | 3 API routes | ||
platform:analytics | Traffic across every customer deployment. | Platform org | Platform org | 2 API routes | ||
org:read | The organization's settings page in Cloud. | ✓ | ✓ | ✓ | ✓ | 2 API routes, Cloud navigation |
org:write | Renaming and deleting the organization; transferring projects (needed in both organizations). | ✓ | ✓ | 4 API routes | ||
audit:read | The organization's audit log. | ✓ | ✓ | 3 API routes | ||
members:read | The organization's members. | ✓ | ✓ | ✓ | ✓ | 1 API route |
members:write | Managing the organization's members. | ✓ | ✓ | Not checked yet | ||
projects:read | Projects and their settings. | ✓ | ✓ | ✓ | ✓ | 3 API routes |
projects:write | Creating projects and changing their settings. | ✓ | ✓ | ✓ | 7 API routes | |
deployments:read | Deployments and their status. | ✓ | ✓ | ✓ | ✓ | 2 API routes |
deployments:write | Redeploying, promoting and rolling back deployments. | ✓ | ✓ | ✓ | 4 API routes | |
env:read | Environment variables. Sensitive values are never returned. | ✓ | ✓ | ✓ | ✓ | 1 API route |
env:write | Adding, changing and deleting environment variables. | ✓ | ✓ | ✓ | 3 API routes | |
domains:read | Custom domains and their status. | ✓ | ✓ | ✓ | ✓ | 3 API routes |
domains:write | Adding, redirecting, moving and removing custom domains; connecting Cloudflare. | ✓ | ✓ | ✓ | 8 API routes | |
resources:read | Databases and buckets. | ✓ | ✓ | ✓ | ✓ | 14 API routes |
resources:write | Creating, linking and deleting databases and buckets. | ✓ | ✓ | ✓ | 18 API routes | |
git:read | Reading repositories, cloning and fetching; reading and opening issues; commenting. | ✓ | ✓ | ✓ | ✓ | 50 API routes, Git over HTTPS: clone and fetch |
git:write | Pushing; creating and deleting repositories; repository settings; opening and merging pull requests. | ✓ | ✓ | ✓ | 16 API routes, Git over HTTPS: push | |
logs:read | Build and runtime logs. | ✓ | ✓ | ✓ | ✓ | 4 API routes |
analytics:read | Traffic analytics for the organization's deployments. | ✓ | ✓ | ✓ | ✓ | 1 API route |
knowledge:read | Knowledge pages and context entries. | ✓ | ✓ | ✓ | ✓ | 6 API routes, context_get, context_list, pages_list, page_get, page_search |
knowledge:write | Creating and editing knowledge pages and context entries. | ✓ | ✓ | ✓ | 4 API routes, context_put, context_delete, page_upsert | |
connectors:read | Connectors, and their tools on the MCP server. | ✓ | ✓ | ✓ | ✓ | 2 API routes, connectors_list, connector tools |
connectors:write | Adding, testing, changing and removing connectors. | ✓ | ✓ | 6 API routes | ||
chat:use | Chat. | ✓ | ✓ | ✓ | ✓ | Not checked yet |
mcp:connect | Connecting MCP clients. | ✓ | ✓ | ✓ | Not checked yet | |
agents:read | Agents, their network requests and jobs. | ✓ | ✓ | ✓ | ✓ | 2 API routes, agent_job_get |
agents:write | Approving and revoking agents, their network access, and exec jobs. | ✓ | ✓ | 4 API routes, agent_job_create, Approving an agent's login | ||
agents:run | Queueing agent jobs. | ✓ | ✓ | ✓ | 3 API routes, agent_job_create, agent_job_cancel | |
mail:read | Reading and organizing mail in the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 12 API routes |
mail:send | Sending mail and saving drafts from the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 7 API routes |
mail:admin | Mail domains, mailboxes, aliases, catch-all addresses and mail usage. | ✓ | ✓ | 13 API routes | ||
calendar:read | Calendars and events of the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 4 API routes |
calendar:write | Creating and changing calendars and events, answering invitations and importing events, in the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 8 API routes |
contacts:read | Address books and contacts of the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 5 API routes |
contacts:write | Creating, changing, importing and deleting contacts and address books in the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 9 API routes |