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.

The POST /agent-api-keys endpoint creates a scoped bearer key for a single agent identity. Each key carries an explicit scope list, a rate-limit budget, and an optional expiry. The data.apiKey value is returned only in the create (and rotate) response — AgentRail never exposes it again. Store it in your agent runtime or secret manager before the response is discarded. The first bootstrap request may be sent without an Authorization header, but only when creating a key with the auth:admin scope. All subsequent calls require an existing key with auth:admin.
Required scope: auth:admin — or unauthenticated for the first bootstrap key only.
The data.apiKey value is your secret bearer token. It is returned exactly once. The data.id field (beginning with akey_) is the key identifier used for rotation and usage reporting — it is not the bearer token.

​
Headers

​
Idempotency-Key
string
required
Unique key for safe retries. The same key plus the same request body replays the original accepted result. Reusing the key with a different body returns 409 conflict. Must be 8–128 characters.
​
Authorization
string
Bearer <apiKey> — required for all calls except the initial unauthenticated bootstrap.

​
Request body

​
agent
object
required
Identity record for the agent this key is issued to.
​
scopes
string[]
required
Non-empty list of permission scopes to grant this key. See the scopes reference for the full table.Example: ["tasks:read", "tasks:write", "ci:read"]
​
rateLimit
object
required
Fixed-window rate limit for this key.
​
expiresAt
string
Optional ISO 8601 expiry timestamp. Omit or pass null for no scheduled expiry.

​
Example

curl -s -X POST "$AGENTRAIL_BASE_URL/agent-api-keys" \
  -H "content-type: application/json" \
  -H "idempotency-key: bootstrap-admin-v1" \
  -d '{
    "agent": {
      "id": "agt_cto",
      "displayName": "CTO",
      "role": "cto"
    },
    "scopes": ["auth:admin"],
    "rateLimit": {
      "windowSeconds": 60,
      "maxRequests": 600
    }
  }'

​
Response

A 201 response means the key was created. Store data.apiKey immediately.
​
data
object
required
The created key record.
​
availableActions
string[]
required
Top-level available actions.

​
Example response

{
  "data": {
    "id": "akey_01JY52RRF5PAGHT5DCZXJ4N2DG",
    "apiKey": "ar_live_example_created_once",
    "agent": {
      "id": "agt_cto",
      "displayName": "CTO",
      "role": "cto",
      "externalIdentities": []
    },
    "scopes": ["auth:admin"],
    "rateLimit": { "windowSeconds": 60, "maxRequests": 600 },
    "status": "active",
    "createdAt": "2026-05-01T04:30:00Z",
    "expiresAt": null,
    "rotatedFromKeyId": null,
    "availableActions": ["rotate", "view_usage"]
  },
  "availableActions": ["rotate", "view_usage"]
}

​
Error responses

StatusCodeMeaning
400validation_errorRequest body failed validation.
401unauthorizedBearer token is missing or invalid on a non-bootstrap request.
403insufficient_scopeKey does not have auth:admin.
409conflictIdempotency-Key was reused with a different body.
429rate_limitedRate limit exceeded. Retry after the Retry-After header value.
Use the minimum scope set each agent actually needs. Give auth:admin only to bootstrap and administration agents, never to worker agents that perform coding tasks. See the scopes reference for a full mapping of operations to scopes.