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

# AgentRail API key scopes and permissions reference

> Complete reference for all AgentRail agent key permission scopes, with guidance on least-privilege scope sets for common agent roles.

Every AgentRail agent key carries an explicit list of scopes. A request fails with `403 insufficient_scope` if the key does not include the scope required by the endpoint being called. Scopes are set at key creation time and can only be changed by rotating the key.

Follow the principle of least privilege: give each agent only the scopes it needs to perform its assigned work. An agent that only reads task status and CI results does not need `ship:write` or `auth:admin`.

## Scope table

| Operation                              | Required scope    |
| -------------------------------------- | ----------------- |
| List or read tasks                     | `tasks:read`      |
| Submit task work                       | `tasks:write`     |
| Read CI summaries                      | `ci:read`         |
| Read review feedback                   | `reviews:read`    |
| Ship or merge work                     | `ship:write`      |
| Stream task events                     | `events:read`     |
| List event subscriptions               | `webhooks:read`   |
| Create or delete event subscriptions   | `webhooks:write`  |
| Sync Linear comments or workflow state | `providers:write` |
| Create or rotate agent keys            | `auth:admin`      |
| Read key usage                         | `usage:read`      |

## All available scopes

<ResponseField name="tasks:read" type="scope">
  Read access to assigned tasks. Required for `GET /tasks/mine` and `GET /tasks/:id`.
</ResponseField>

<ResponseField name="tasks:write" type="scope">
  Write access for task mutations. Required for `POST /tasks/:id/submit`.
</ResponseField>

<ResponseField name="ci:read" type="scope">
  Read access to CI summaries. Required for `GET /tasks/:id/ci-status`.
</ResponseField>

<ResponseField name="reviews:read" type="scope">
  Read access to PR review feedback. Required for `GET /tasks/:id/review-feedback`.
</ResponseField>

<ResponseField name="ship:write" type="scope">
  Write access to trigger merge and deploy operations. Required for `POST /tasks/:id/ship`.
</ResponseField>

<ResponseField name="events:read" type="scope">
  Read access to the SSE event stream. Required for `GET /task-events/stream`.
</ResponseField>

<ResponseField name="webhooks:read" type="scope">
  Read access to event subscriptions. Required for `GET /event-subscriptions`.
</ResponseField>

<ResponseField name="webhooks:write" type="scope">
  Write access to create and delete event subscriptions. Required for `POST /event-subscriptions` and `DELETE /event-subscriptions/:subscriptionId`.
</ResponseField>

<ResponseField name="providers:write" type="scope">
  Write access to sync Linear comments and workflow state through provider adapters.
</ResponseField>

<ResponseField name="auth:admin" type="scope">
  Full access to create and rotate agent API keys. Required for `POST /agent-api-keys` and `POST /agent-api-keys/:keyId/rotate`. Also satisfies `usage:read`.
</ResponseField>

<ResponseField name="usage:read" type="scope">
  Read access to key usage counters. Required for `GET /agent-api-keys/:keyId/usage`.
</ResponseField>

## Recommended scope sets by agent role

| Agent responsibility                              | Minimum scopes                                                       |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| Read assigned tasks only                          | `tasks:read`                                                         |
| Submit completed work                             | `tasks:read`, `tasks:write`                                          |
| Inspect CI results                                | `ci:read`                                                            |
| Inspect review feedback                           | `reviews:read`                                                       |
| Full task lifecycle (read, submit, observe, ship) | `tasks:read`, `tasks:write`, `ci:read`, `reviews:read`, `ship:write` |
| Stream task events                                | `events:read`                                                        |
| Manage webhook subscriptions                      | `webhooks:read`, `webhooks:write`                                    |
| Bootstrap and key administration                  | `auth:admin`, `usage:read`                                           |

## `auth:admin` key guidelines

<Warning>
  `auth:admin` grants the ability to create new keys with any scope. Never assign `auth:admin` to worker agents that perform coding, CI observation, or shipping work. Treat keys with this scope like infrastructure secrets.
</Warning>

Use `auth:admin` keys only for:

* The initial bootstrap key created before any agent keys exist.
* Operator scripts that rotate or provision agent keys.
* Administration tooling that reports on key usage.

All other agents should receive a narrow scope set tailored to their specific role.

## Scope enforcement

When a request fails because of a missing scope, the response includes the required and granted scopes:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Agent API key does not grant the required scope.",
    "details": {
      "requiredScope": "webhooks:write",
      "grantedScopes": ["ci:read"],
      "availableActions": ["request_scope"]
    }
  }
}
```

To fix this, rotate the key with the additional required scopes, or create a new key that includes them.