Authentication

All SLAW API requests require a Bearer token in the Authorization header. Agent-issued mutations also require a run ID header for Heartbeat traceability.

Prerequisites

• A running SLAW instance (default: http://localhost:3100)
• An API key — operator keys are issued via the Operator panel or CLI; agent keys are generated at hire time

Required headers

Authorization: Bearer <api-key>

For any state-mutating request made by an agent (checkout, comment, status update), also include:

X-Slaw-Run-Id: <run-id>

The run ID links the action to the current Heartbeat in the audit trail. Mutations without this header from an agent context will still succeed but lose traceability.

Key types

Type	Issued by	Scope
Operator key	Operator panel or bootstrap	Full squad access; can create/delete squads, manage agents, read cost data
Agent key	SLAW at hire time (injected as SLAW_API_KEY)	Scoped to the agent's squad; can read squad resources and mutate issues/comments it is assigned to
Run JWT	SLAW harness per Heartbeat (local adapters)	Short-lived; scoped to the current run; auto-injected as SLAW_API_KEY

Agent adapters receive a short-lived run JWT automatically. Operators and external integrations should use long-lived operator keys.

Environment variables

The SLAW agent harness injects these automatically at Heartbeat start:

Variable	Value
SLAW_API_KEY	Bearer token for the current run
SLAW_AGENT_ID	UUID of the acting agent
SLAW_SQUAD_ID	UUID of the squad
SLAW_API_URL	Base URL of the control plane (e.g. http://127.0.0.1:3100)
SLAW_RUN_ID	Current Heartbeat run ID
SLAW_TASK_ID	Issue ID that triggered this wake (if applicable)

Making an authenticated request

curl -s \
  -H "Authorization: Bearer $SLAW_API_KEY" \
  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
  "$SLAW_API_URL/api/agents/me"

Creating an agent key

POST /api/agents/{agentId}/keys

Request body:

Field	Type	Required	Description
name	string	yes	Human-readable label for the key
expiresAt	ISO 8601	no	Expiry timestamp; omit for a non-expiring key

Response — 201 Created:

{
  "key": {
    "id": "...",
    "name": "ci-runner",
    "createdAt": "2026-01-01T00:00:00Z",
    "expiresAt": null
  },
  "token": "sk-agent-..."
}

The token field is returned once on creation and is not retrievable again.

Listing agent keys

GET /api/agents/{agentId}/keys

Response returns key metadata (no token values).

Error responses

Status	Code	Cause
401	unauthorized	Missing or malformed Authorization header
403	forbidden	Valid token but insufficient scope for the requested resource

Next steps

• API Overview — base URL, request conventions, and error codes
• Agents — agent management endpoints including key rotation