Scopes & Permissions

Qumo Deploy uses a two-tiered authorization system: Scopes (enforced at the Identity Token level) and Permissions (enforced at the IAM role level).

Source of truth: This page is the canonical reference for Identity Token scope strings and IAM permission names. Relay credentials are signed by your app with its own signing keys and carry path grants, not these scopes.

Identity Token Scopes

Scopes define the maximum set of control-plane actions an Identity Token may perform, regardless of its User or Identity principal’s IAM permissions.

Scope	Description	Protected Routes
`*`	Wildcard. Allows any action the principal has IAM permissions for	All routes
`project:read`	Read projects, signing keys and IP allowlists	`GET /v1/projects`, `GET /v1/projects/{id}/signing-keys`
`usage:read`	Usage metrics and billing summaries	`GET /v1/projects/{id}/usage`, `GET /v1/organizations/{id}/usage`, `GET /v1/projects/{id}/billing/summary`
`audit:read`	View audit log entries and webhook config	`GET /v1/audit-log`, `GET /v1/projects/{id}/audit-log`, `GET /v1/audit-webhooks`
`audit:admin`	Configure audit webhooks	`PUT /v1/audit-webhooks`
`signing_keys:admin`	Register and revoke the keys your app signs relay credentials with	`POST /v1/projects/{id}/signing-keys`, `POST /v1/projects/{id}/signing-keys/{kid}/revoke`
`iam:read`	List IAM roles, bindings and identities	`GET /v1/roles`, `GET /v1/projects/{id}/iam-bindings`, `GET /v1/organizations/{id}/iam-bindings`, `GET /v1/projects/{id}/identities`
`iam:admin`	Create and delete IAM bindings, invitations, identities and their tokens, and IP allowlist entries	`POST /v1/projects/{id}/iam-bindings`, `POST /v1/organizations/{id}/iam-bindings`, `DELETE /v1/iam-bindings/{binding_id}`, `POST /v1/invitations`, `POST /v1/projects/{id}/identities`
`organization:admin`	Manage organization settings, projects, invoices, notification policies, verified domains and managed accounts	`GET/POST/PATCH/DELETE /v1/organizations`, `POST/PATCH/DELETE /v1/projects`, `GET /v1/organizations/{id}/invoices`, `/v1/notifications/policies`, `GET/POST /v1/organizations/{id}/domains`, `POST /v1/organizations/{id}/domains/{domainID}/verify`, `DELETE /v1/organizations/{id}/domains/{domainID}`, `GET /v1/organizations/{id}/managed-accounts`, `GET /v1/organizations/{id}/outside-memberships`, `POST /v1/organizations/{id}/managed-accounts/{userID}/deactivate` and `/reactivate`
`billing:admin`	Organization budget, billing export, payment methods, Stripe checkout and portal sessions, operator plan assignment	`GET/PUT /v1/organizations/{id}/budget`, `GET /v1/billing/export`, `/v1/organizations/{id}/payment-methods`, `POST /v1/billing/checkout-sessions`, `POST /v1/organizations/{id}/subscription/cancel` and `/resume`, `PUT /v1/organizations/{id}/plan`

Scope vs. Permission: Even if a key has the * scope, it cannot perform an action unless the associated principal (User or Identity) has the required IAM Permission.

IAM Permissions

Permissions are granular actions that can be grouped into IAM Roles. They are typically scoped to either a Organization or a Project.

Organization-level Permissions

Permission	Description
`organization.get`	View organization settings and details.
`organization.list`	List all organizations (Platform Admin only).
`organization.create`	Create organizations via the admin API. Users create their own organizations via self-service (`POST /v1/auth/organizations`).
`organization.update`	Modify organization settings (name, billing email).
`organization.delete`	Delete an organization and all its resources.
`project.create`	Create new projects within the organization.
`project.list`	List all projects belonging to the organization.
`audit.webhook_read`	View audit webhook configuration.
`audit.webhook_write`	Modify audit webhook configuration.
`notification.policy_admin`	Create, list, test and delete the organization’s notification policies.
`billing.payment_methods_read`	List the organization’s payment methods.
`billing.payment_methods_write`	Add, remove and set the default payment method, open Stripe Checkout or the billing portal, and cancel the subscription or undo a scheduled cancellation.
`billing.export_read`	Download the organization’s usage as CSV, `GET /v1/billing/export`.
`billing.budget_get`, `billing.budget_update`	Read and set the organization’s monthly budget: its limit, alert threshold and stop at limit, with this period’s cost and the alerts sent. Held by Organization Admin only.
`organization.domain_list`	List the organization’s domains and their verification state (scope `organization:admin`). Held by Organization Admin.
`organization.domain_add`	Add a domain and get the TXT record to publish at `_qumo-verification.<domain>` (scope `organization:admin`). A domain another organization has verified, and public mail domains, cannot be added. Held by Organization Admin.
`organization.domain_verify`	Look the TXT record up to verify a domain, or restore a lapsed or frozen one (scope `organization:admin`). Held by Organization Admin.
`organization.domain_release`	Give a domain up so another organization may claim it (scope `organization:admin`). Release is never automatic. Held by Organization Admin; a platform admin may release a domain once its new owner has proved control.
`organization.managed_account_list`	List the organization’s managed accounts (every account whose email is at one of its claimed domains, exact domain only) with their state, and the roles they hold in other organizations (scope `organization:admin`). Those memberships are listed only, never refused or removed. Held by Organization Admin.
`organization.managed_account_deactivate`	Deactivate a managed account (scope `organization:admin`): it can no longer sign in, its sessions and device codes are deleted and its personal tokens revoked, and every credential it still presents is refused. It is a state, never a deleted row, and no membership changes. Not your own account, and not a platform administrator’s. Held by Organization Admin.
`organization.managed_account_reactivate`	Let a deactivated managed account sign in again (scope `organization:admin`). Held by Organization Admin.
`project.suspend`	Suspend or resume a project, `PUT /v1/projects/{id}/suspension` (Platform Admin only). While suspended, managed relays don’t trust the project’s signing keys.
`organization.suspend`	Suspend or resume a whole organization, `PUT /v1/organizations/{id}/suspension` (Platform Admin only). While suspended, every project of the organization counts as suspended, including projects created later; resuming restores each project’s own state.
`user.revoke_access`	End every console and CLI session and revoke every personal access token of a user, `POST /v1/users/{user_id}/access-revocation` (Platform Admin only; a reason is required). The user can sign in again afterwards.
`billing.quota_update`	Set a project’s live-broadcast quota, `PUT /v1/projects/{id}/broadcast-quota` (Platform Admin only; default 10,000; there is no viewer quota).
`billing.plan_assign`	Assign an organization’s plan directly, for organizations not billed through Stripe (Platform Admin only; refused with 409 while the organization has a live Stripe subscription).

Project-level Permissions

Permission	Description
`project.get`	View project metadata.
`project.update`	Rename or modify project settings.
`project.delete`	Delete the project and all its keys.
`iam.binding_list`	List IAM roles and bindings.
`iam.binding_create`	Grant roles to users or identities, directly or by invitation: only roles whose every permission the caller holds (so a Project Admin cannot grant Organization Admin).
`iam.binding_delete`	Revoke roles from principals.
`signing_key.list`	List the project’s signing keys (scope `project:read`).
`signing_key.manage`	Register and revoke the project’s signing keys (scope `signing_keys:admin`).
`usage.get`	Read usage and billing summaries for the project or organization.
`audit.list`	Read audit log entries.
`identity.list`	List the project’s Identities and their tokens.
`identity.create`, `identity.delete`	Create and delete Identities.
`identity.token_create`, `identity.token_revoke`	Mint and revoke Identity Tokens.
`identity.ip_allowlist.list`, `identity.ip_allowlist.create`, `identity.ip_allowlist.delete`	Read and change an Identity’s IP allowlist.

Identities

An Identity belongs to one project, and its tokens act only there: on its own project, and on its own organization for organization-level routes. A request whose path or ?organization_id= names another project or another organization answers 403 Forbidden, whatever roles the Identity holds. Granting an Identity a role that gives it a permission it did not already hold (on its organization, or on its project) revokes every token it already has, since whoever minted those tokens may not hold the new permission. Mint a new token after the grant. A role that adds nothing new, such as roles/project.viewer for an Identity that is already a project admin, leaves its tokens alone. When a grant revokes tokens, the POST .../iam-bindings response carries revoked_identity_tokens (the count, omitted when zero), and so does the iam.binding_create audit record. A token request that races such a grant either gets a token the grant then revokes, or answers 409 Conflict; mint again.

​Scopes & Permissions

​Identity Token Scopes

​IAM Permissions

​Organization-level Permissions

​Project-level Permissions

​Identities

Scopes & Permissions

Identity Token Scopes

IAM Permissions

Organization-level Permissions

Project-level Permissions

Identities