Skip to main content

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.

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

OperationRequired scope
List or read taskstasks:read
Submit task worktasks:write
Read CI summariesci:read
Read review feedbackreviews:read
Ship or merge workship:write
Stream task eventsevents:read
List event subscriptionswebhooks:read
Create or delete event subscriptionswebhooks:write
Sync Linear comments or workflow stateproviders:write
Create or rotate agent keysauth:admin
Read key usageusage:read

​
All available scopes

​
tasks:read
scope
Read access to assigned tasks. Required for GET /tasks/mine and GET /tasks/:id.
​
tasks:write
scope
Write access for task mutations. Required for POST /tasks/:id/submit.
​
ci:read
scope
Read access to CI summaries. Required for GET /tasks/:id/ci-status.
​
reviews:read
scope
Read access to PR review feedback. Required for GET /tasks/:id/review-feedback.
​
ship:write
scope
Write access to trigger merge and deploy operations. Required for POST /tasks/:id/ship.
​
events:read
scope
Read access to the SSE event stream. Required for GET /task-events/stream.
​
webhooks:read
scope
Read access to event subscriptions. Required for GET /event-subscriptions.
​
webhooks:write
scope
Write access to create and delete event subscriptions. Required for POST /event-subscriptions and DELETE /event-subscriptions/:subscriptionId.
​
providers:write
scope
Write access to sync Linear comments and workflow state through provider adapters.
​
auth:admin
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.
​
usage:read
scope
Read access to key usage counters. Required for GET /agent-api-keys/:keyId/usage.
Agent responsibilityMinimum scopes
Read assigned tasks onlytasks:read
Submit completed worktasks:read, tasks:write
Inspect CI resultsci:read
Inspect review feedbackreviews:read
Full task lifecycle (read, submit, observe, ship)tasks:read, tasks:write, ci:read, reviews:read, ship:write
Stream task eventsevents:read
Manage webhook subscriptionswebhooks:read, webhooks:write
Bootstrap and key administrationauth: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.