> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scopes & Permissions

> Canonical reference for API key scopes and IAM permissions in Qumo Deploy.

# Scopes & Permissions

Qumo Deploy uses a two-tiered authorization system: **Scopes** (enforced at the token/API key level) and **Permissions** (enforced at the IAM role level).

<Note>
  **Source of truth:** This page is the canonical reference for all API key scope strings and IAM permission names.
</Note>

## API Key Scopes

Scopes define the maximum set of actions a specific API key is allowed to perform, regardless of the principal's IAM permissions.

| Scope               | Description                                                           | Protected Routes                                                                                                                      |
| :------------------ | :-------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `*`                 | **Wildcard.** Allows any action the principal has IAM permissions for | All routes                                                                                                                            |
| `project:read`      | List projects and API keys                                            | `GET /admin/v1/projects`, `GET /admin/v1/projects/{id}/api-keys`                                                                      |
| `usage:read`        | Usage metrics and billing data                                        | `GET /admin/v1/projects/{id}/usage`, `GET /admin/v1/tenants/{id}/usage`, key usage                                                    |
| `audit:read`        | View audit log entries and webhook config                             | `GET /admin/v1/audit-log`, `GET /admin/v1/audit-webhooks`                                                                             |
| `audit:admin`       | Configure audit webhooks                                              | `PUT /admin/v1/audit-webhooks`                                                                                                        |
| `credentials:admin` | Issue and revoke credentials                                          | `POST /admin/v1/projects/{id}/credentials`, `POST /admin/v1/credentials/{jti}/revoke`                                                 |
| `iam:read`          | List IAM roles and bindings                                           | `GET /admin/v1/roles`, `GET /admin/v1/projects/{id}/iam-bindings`, `GET /admin/v1/tenants/{id}/iam-bindings`                          |
| `iam:admin`         | Create and delete IAM bindings                                        | `POST /admin/v1/projects/{id}/iam-bindings`, `POST /admin/v1/tenants/{id}/iam-bindings`, `DELETE /admin/v1/iam-bindings/{binding_id}` |
| `tenant:admin`      | Manage tenant settings, projects, invoices, and notification policies | `GET/POST/PATCH/DELETE /admin/v1/tenants`, tenant icon, `GET /admin/v1/tenants/{id}/invoices`                                         |
| `billing:admin`     | Budget configuration, alerts, billing export, payment methods         | `GET/POST /admin/v1/projects/{id}/budget`, `GET /admin/v1/projects/{id}/alerts`, billing export, SKU budgets                          |

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

## IAM Permissions

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

### Tenant-level Permissions

| Permission            | Description                                                                                                           |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `tenant.get`          | View tenant settings and details.                                                                                     |
| `tenant.list`         | List all tenants (Platform Admin only).                                                                               |
| `tenant.create`       | Create tenants via the admin API. Users create their own workspaces via self-service (`POST /admin/v1/auth/tenants`). |
| `tenant.update`       | Modify tenant settings (name, billing email, icon).                                                                   |
| `tenant.delete`       | Delete a tenant and all its resources.                                                                                |
| `project.create`      | Create new projects within the tenant.                                                                                |
| `project.list`        | List all projects belonging to the tenant.                                                                            |
| `audit.webhook_read`  | View audit webhook configuration.                                                                                     |
| `audit.webhook_write` | Modify audit webhook configuration.                                                                                   |

### 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 bots.           |
| `iam.binding_delete` | Revoke roles from principals.           |
| `api_key.list`       | List project-scoped API keys.           |
| `api_key.create`     | Create new API keys within the project. |
| `api_key.delete`     | Revoke/delete project API keys.         |