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

# Authorization

The Platform API uses **scopes** to define fine-grained access control. Scopes are selected when [creating an API key](/admin/apikeys).

## How scopes work

Scope names follow a `resource:action` format (e.g. `devices:read`).

Nearly all API endpoints require one or more scopes, shown on the endpoint's API Reference page. If an API key is missing a required scope, the request returns `403 Forbidden`.

## Scope tiers

Most resources follow a common tier pattern:

| Tier     | Access                                                       |
| -------- | ------------------------------------------------------------ |
| `manage` | All operations—superset of all other scopes for the resource |
| `read`   | Get or list operations                                       |
| `write`  | Create or update operations                                  |

The `write` scope does **not** include `read` access—if you need both, select both scopes.

Some resources have additional granular scopes beyond the standard tiers (e.g. `deployments:stage`). The `manage` scope always includes everything for the resource.

## Scopes by resource

### Config instances

| Scope                     | Permissions    |
| ------------------------- | -------------- |
| `config_instances:manage` | all operations |
| `config_instances:read`   | get, list      |
| `config_instances:write`  | create         |

### Config schemas

| Scope                   | Permissions    |
| ----------------------- | -------------- |
| `config_schemas:manage` | all operations |
| `config_schemas:read`   | get, list      |
| `config_schemas:write`  | create, update |

### Config types

| Scope                 | Permissions    |
| --------------------- | -------------- |
| `config_types:manage` | all operations |
| `config_types:read`   | get, list      |
| `config_types:write`  | create, update |

### Deployments

| Scope                 | Permissions    |
| --------------------- | -------------- |
| `deployments:manage`  | all operations |
| `deployments:read`    | get, list      |
| `deployments:write`   | create         |
| `deployments:stage`   | stage          |
| `deployments:deploy`  | deploy         |
| `deployments:archive` | archive        |

### Devices

| Scope               | Permissions                        |
| ------------------- | ---------------------------------- |
| `devices:manage`    | all operations                     |
| `devices:read`      | get, list, ping                    |
| `devices:provision` | create, activate, reactivate, list |
| `devices:write`     | create, update                     |
| `devices:delete`    | delete                             |

### Git commits

| Scope                | Permissions    |
| -------------------- | -------------- |
| `git_commits:manage` | all operations |
| `git_commits:read`   | get, list      |
| `git_commits:write`  | create         |

### Provisioning tokens

| Scope                        | Permissions    |
| ---------------------------- | -------------- |
| `provisioning_tokens:manage` | all operations |
| `provisioning_tokens:write`  | create         |

### Releases

| Scope             | Permissions    |
| ----------------- | -------------- |
| `releases:manage` | all operations |
| `releases:read`   | get, list      |
| `releases:write`  | create, update |

## Principle of least privilege

While granting an API unrestricted access to your resources is convenient, it is a security risk. We recommend using the **principle of least privilege** to grant the least amount of access possible.