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 | 88 API routes | ||
platform:infra | The region and location registry. | Platform org | Platform org | 6 API routes | ||
platform:analytics | Traffic across every customer deployment. | Platform org | Platform org | 2 API routes | ||
platform:coverage | Posting test coverage runs of the platform's repository (its nightly pipeline). | Platform org | Platform org | 2 API routes | ||
org:read | The organization's settings page in Cloud. | ✓ | ✓ | ✓ | ✓ | 9 API routes, Cloud navigation |
org:write | Renaming and deleting the organization; transferring projects (needed in both organizations). | ✓ | ✓ | 9 API routes | ||
audit:read | The organization's audit log. | ✓ | ✓ | 3 API routes | ||
tenant:read | Tenant: users, groups, roles, applications, sign-in logs and policies. | ✓ | ✓ | 16 API routes, tenant_overview, tenant_users_list, tenant_user_get, tenant_groups_list, tenant_group_get, tenant_roles_list, tenant_sign_ins, tenant_policy_get | ||
tenant:write | Tenant: inviting, blocking and removing users, groups, role assignments, applications and policies. | ✓ | ✓ | 45 API routes, tenant_invite, tenant_user_update, tenant_user_block, tenant_user_unblock, tenant_user_revoke_sessions, tenant_group_member_set | ||
members:read | The organization's members. | ✓ | ✓ | ✓ | ✓ | 2 API routes |
members:write | Managing the organization's members. | ✓ | ✓ | Not checked yet | ||
projects:read | Serverless App Services and their settings. | ✓ | ✓ | ✓ | ✓ | 8 API routes |
projects:write | Creating Serverless App Services and changing their settings. | ✓ | ✓ | ✓ | 11 API routes | |
deployments:read | Deployments and their status. | ✓ | ✓ | ✓ | ✓ | 4 API routes |
deployments:write | Redeploying, promoting and rolling back deployments. | ✓ | ✓ | ✓ | 5 API routes | |
env:read | Environment variables. Sensitive values are never returned. | ✓ | ✓ | ✓ | ✓ | 8 API routes, secrets_list, secret_get |
env:write | Adding, changing and deleting environment variables and secrets, and reading secrets their access rules allow. | ✓ | ✓ | ✓ | 10 API routes, secret_get, secret_set | |
keys:read | Every key that protects the organization's data, its versions, use and audit. Never key material. | ✓ | ✓ | 2 API routes, keys_list | ||
keys:use | Encrypting, decrypting, signing and verifying with the organization's own keys. | ✓ | ✓ | ✓ | 5 API routes, keys_encrypt, keys_decrypt, keys_sign, keys_verify | |
keys:write | Creating, rotating, scheduling, re-encrypting, disabling and destroying keys; who may read secrets. | ✓ | ✓ | 9 API routes | ||
domains:read | Custom domains and their status. | ✓ | ✓ | ✓ | ✓ | 8 API routes |
domains:write | Adding, redirecting, moving and removing custom domains; connecting Cloudflare. | ✓ | ✓ | ✓ | 9 API routes | |
resources:read | Databases and buckets. | ✓ | ✓ | ✓ | ✓ | 22 API routes, databases_list, database_describe, database_query, database_scan, database_item_get, buckets_list, bucket_list, bucket_download_url |
resources:write | Creating, linking and deleting databases and buckets. | ✓ | ✓ | ✓ | 33 API routes, database_item_put, database_item_delete, bucket_upload_url, bucket_delete | |
git:read | Reading repositories, cloning and fetching; reading and opening issues; commenting. | ✓ | ✓ | ✓ | ✓ | 102 API routes, Git over HTTPS: clone and fetch |
git:write | Pushing; creating and deleting repositories; repository settings; opening and merging pull requests; running, re-running and cancelling pipelines. | ✓ | ✓ | ✓ | 25 API routes, Git over HTTPS: push | |
git:admin | Pipelines' secrets, variables and environments (their reviewers, wait timers and branch rules), caches and artifacts. Owners and admins. | ✓ | ✓ | 21 API routes | ||
logs:read | Build and runtime logs. | ✓ | ✓ | ✓ | ✓ | 4 API routes |
analytics:read | Traffic analytics for the organization's deployments. | ✓ | ✓ | ✓ | ✓ | 1 API route, project_traffic |
knowledge:read | Notes pages and context entries. | ✓ | ✓ | ✓ | ✓ | 14 API routes, context_get, context_list, pages_list, page_get, page_search |
knowledge:write | Creating and editing knowledge pages and context entries. | ✓ | ✓ | ✓ | 9 API routes, context_put, context_delete, page_upsert | |
connectors:read | Connectors, and their tools on the MCP server. | ✓ | ✓ | ✓ | ✓ | 5 API routes, connectors_list, connector tools |
connectors:write | Adding, testing, changing and removing connectors. | ✓ | ✓ | 7 API routes | ||
chat:use | Caity. | ✓ | ✓ | ✓ | ✓ | Not checked yet |
mcp:connect | Connecting MCP clients. | ✓ | ✓ | ✓ | Not checked yet | |
agents:read | Agents, their network requests and jobs. | ✓ | ✓ | ✓ | ✓ | 7 API routes, agent_job_get |
agents:write | Approving and revoking agents, their network access, and exec jobs. | ✓ | ✓ | 5 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. | ✓ | ✓ | ✓ | ✓ | 26 API routes |
mail:send | Sending mail and saving drafts from the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 12 API routes |
mail:admin | Mail domains, mailboxes, aliases, catch-all addresses and mail usage. | ✓ | ✓ | 14 API routes | ||
calendar:read | Calendars and events of the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 8 API routes |
calendar:write | Creating and changing calendars and events, answering invitations and importing events, in the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 12 API routes |
contacts:read | Address books and contacts of the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 9 API routes |
contacts:write | Creating, changing, importing and deleting contacts and address books in the mailboxes you're a member of. | ✓ | ✓ | ✓ | ✓ | 13 API routes |
issues:read | Issue spaces, issues, boards, filters, dashboards and reports you can browse (each space's permission scheme applies). | ✓ | ✓ | ✓ | ✓ | 61 API routes, issues_meta, issues_search, issues_report, issues_agenda, issue_get, boards_list, board_get, filters_list |
issues:write | Creating spaces, issues and filters; working on issues where the space's permission scheme allows it. | ✓ | ✓ | ✓ | 56 API routes, sprint_create, sprint_plan, sprint_start, sprint_complete, issue_create, issue_update, issue_transition, issue_comment, issue_link, issue_worklog, issues_rank, issue_move, issue_delete, space_create | |
issues:admin | Issue configuration (statuses, types, workflows, fields, screens, permission schemes), every space, and deleting spaces. | ✓ | ✓ | 22 API routes | ||
maps:read | Maps: live aircraft, flight history, and the saved maps, flight watches and notification groups shared with the organization. | ✓ | ✓ | ✓ | ✓ | 65 API routes, aircraft_find, aircraft_track, flight_watches_list, flight_logs_list, flight_log_get, flight_watch_events, maps_locations_list, my_location_status, incidents_list, incident_get, watch_zones_list, watch_zone_events |
maps:write | Saving places and maps, creating and changing flight watches and notification groups, and push subscriptions. | ✓ | ✓ | ✓ | ✓ | 30 API routes, flight_watch_create, circling_alert_create, maps_location_create, maps_location_update, maps_location_delete, my_location_delete, flight_watch_pause, flight_watch_restart, watch_zone_create, watch_zone_update, watch_zone_pause, watch_zone_delete |
drive:read | Drive: the organization's files and folders you can open (your My Drive, shared drives you're in, and what's shared with you). | ✓ | ✓ | ✓ | ✓ | 178 API routes |
drive:write | Drive: uploading, organizing, sharing and deleting the organization's files where your access allows it. | ✓ | ✓ | ✓ | ✓ | Not checked yet |
crm:read | Customers: reading accounts, contacts, leads, opportunities and activities that sharing allows, list views, search and the pipeline. | ✓ | ✓ | ✓ | ✓ | 47 API routes, crm_objects, crm_search, crm_records_list, crm_record_get, crm_pipeline_summary |
crm:write | Customers: creating records, changing and deleting those sharing allows, logging activities, converting leads, imports. | ✓ | ✓ | ✓ | 8 API routes, crm_record_create, crm_record_update, crm_activity_log | |
crm:admin | Customers settings: objects, fields, validation rules, indexes, pipelines, sharing and role permissions. Includes seeing and changing every record. | ✓ | ✓ | 13 API routes | ||
marketing:read | Marketing: segments, lists, content, campaigns and their results, consent and engagement. | ✓ | ✓ | ✓ | ✓ | 88 API routes, marketing_segments_list, marketing_segment_get, marketing_segment_estimate, marketing_lists_list, marketing_campaigns_list, marketing_campaign_get, marketing_journeys_list, marketing_journey_get, marketing_consent_get, marketing_stats_daily, marketing_forms_list |
marketing:write | Marketing: building segments, lists, templates and the content library, importing lists, and drafting campaigns. | ✓ | ✓ | ✓ | marketing_campaign_create, marketing_campaign_request_approval, marketing_journey_create | |
marketing:send | Marketing: scheduling, sending, pausing and cancelling campaigns, and approving others' campaigns. | ✓ | ✓ | Not checked yet | ||
marketing:admin | Marketing settings: sender, physical address, topics, approvals, frequency caps, send times and the brand kit, and changing an address's consent. | ✓ | ✓ | Not checked yet | ||
health:read | Health: your own summaries, charts, samples and what others share with you. Keys and connected apps only when you allow it in Health → Privacy; Caity only summaries, and only when allowed. | ✓ | ✓ | ✓ | ✓ | Not checked yet |
health:write | Health: adding, changing and deleting your own samples and syncing them. Keys and connected apps only when you allow it in Health → Privacy; never privacy settings. | ✓ | ✓ | ✓ | ✓ | Not checked yet |
weather:read | Weather (personal, in no organization): forecasts, air quality and place search, and reading your own saved places. Held in any of your organizations, or none. | ✓ | ✓ | ✓ | ✓ | 3 API routes, weather_forecast, weather_places_search |
weather:write | Weather: changing your own saved places and units. | ✓ | ✓ | ✓ | ✓ | 1 API route |
food:read | Food (personal, in no organization): your recipes and collections, and your household's meal plan, shopping lists and pantry. Held in any of your organizations, or none; a key acts for the person who made it. | ✓ | ✓ | ✓ | ✓ | 26 API routes, food_recipes_search, food_recipe_get, food_suggestions, food_what_can_i_cook, food_plan_get, food_substitute, food_use_soon, food_spending, food_plan_meals, food_plan_add, food_shopping_list, food_list_add, food_pantry_add, food_recipe_save |
food:write | Food: adding and changing recipes, the plan, lists and the pantry, importing, and your Food settings. | ✓ | ✓ | ✓ | ✓ | 50 API routes |