AgentRail API key scopes and permissions reference

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

scope

Read access to assigned tasks. Required for GET /tasks/mine and GET /tasks/:id.

scope

Write access for task mutations. Required for POST /tasks/:id/submit.

scope

Read access to CI summaries. Required for GET /tasks/:id/ci-status.

scope

Read access to PR review feedback. Required for GET /tasks/:id/review-feedback.

scope

Write access to trigger merge and deploy operations. Required for POST /tasks/:id/ship.

scope

Read access to the SSE event stream. Required for GET /task-events/stream.

scope

Read access to event subscriptions. Required for GET /event-subscriptions.

scope

Write access to create and delete event subscriptions. Required for POST /event-subscriptions and DELETE /event-subscriptions/:subscriptionId.

scope

Write access to sync Linear comments and workflow state through provider adapters.

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.

scope

Read access to key usage counters. Required for GET /agent-api-keys/:keyId/usage.

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

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.

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:

{
  "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.

Tasks

Auth & Keys

Events & Webhooks

AgentRail API key scopes and permissions reference

Scope table

All available scopes

Recommended scope sets by agent role

`auth:admin` key guidelines

Scope enforcement

​Scope table

​All available scopes

​Recommended scope sets by agent role

​auth:admin key guidelines

​Scope enforcement

Scope table

All available scopes

Recommended scope sets by agent role

`auth:admin` key guidelines

Scope enforcement