Delegation

Delegation is how you give an agent authority without giving it the keys.

A delegation token answers four questions about a single agent run:

1. What can it do? — the action surface (specific verbs and resources).
2. How much can it spend? — the spend cap (maxUSD).
3. For how long? — the time-to-live (TTL).
4. Who can override? — the approval chain (named humans).

The Authorization Boundary reads the delegation on every action and either passes, blocks, or escalates. Broad API keys are a liability. Scoped delegation is how enterprises let agents act without giving them root.

Token shape

{
  "delegation": {
    "id": "del_8e1d2f4a9c3b6e7d",
    "agentId": "agent_travel_bot_v3",
    "actions": ["reserve", "book", "cancel"],
    "resources": ["hotel/*", "flight/*"],
    "maxUSD": 500,
    "currency": "USD",
    "approvalChain": ["lead@company.com"],
    "ttl": 3600,
    "issuedAt": "2026-04-25T14:00:00Z",
    "expiresAt": "2026-04-25T15:00:00Z",
    "revoked": false
  }
}

{
  "delegation": {
    "id": "del_8e1d2f4a9c3b6e7d",
    "agentId": "agent_travel_bot_v3",
    "actions": ["reserve", "book", "cancel"],
    "resources": ["hotel/*", "flight/*"],
    "maxUSD": 500,
    "currency": "USD",
    "approvalChain": ["lead@company.com"],
    "ttl": 3600,
    "issuedAt": "2026-04-25T14:00:00Z",
    "expiresAt": "2026-04-25T15:00:00Z",
    "revoked": false
  }
}

actions and resources use a glob-style match. maxUSD: 0 means "agent can read but cannot spend." ttl is in seconds; expired tokens are rejected at the boundary stage with code: 'delegation_expired'.

Approval chains

When an action exceeds the delegation's bounds — or when the rule explicitly requires a human — the action enters the awaiting_approval state. The named approvers receive a notification (email, Slack, webhook) with:

• The proposed action.
• The reason for escalation.
• A signed approval link.

Approvers click → the action proceeds with their signature added to the receipt. Decline → the action is blocked with code: 'approval_denied'.

{
  "kind": "executed",
  "transaction_id": "txn_…",
  "receipt": {
    "version": { "spec": "ep-receipt/2026-04-27" },
    "eventType": "ORIGINAL",
    "paymentStatus": "charged",
    "metadata": {
      "approvedBy": [
        {
          "email": "lead@company.com",
          "approvedAt": "2026-04-25T14:31:55.103Z",
          "signature": "…"
        }
      ]
    }
    /* …rest of v2.2 envelope */
  }
}

{
  "kind": "executed",
  "transaction_id": "txn_…",
  "receipt": {
    "version": { "spec": "ep-receipt/2026-04-27" },
    "eventType": "ORIGINAL",
    "paymentStatus": "charged",
    "metadata": {
      "approvedBy": [
        {
          "email": "lead@company.com",
          "approvedAt": "2026-04-25T14:31:55.103Z",
          "signature": "…"
        }
      ]
    }
    /* …rest of v2.2 envelope */
  }
}

Multi-party approval requires all named approvers to sign before the action commits. Single-party approval requires any one.

Revocation

A delegation can be revoked at any time. Revocation takes effect at the next boundary evaluation — in-flight actions are blocked before commit.

The protocol-level revocation surface (CLI command, webhook event, and the multi-instance propagation guarantees) lands when the production gateway exits private beta. Until then, the sandbox treats every request as a fresh delegation.

Replay safety

Delegation tokens are single-use within their TTL by default. Replaying a token after its referenced action has committed produces a code: 'replay_detected' error. Idempotency keys override this for explicit retry semantics — see Errors.

Why scoped delegation matters

Most existing agent platforms hand agents broad API keys. The agent then has authority over everything the key has authority over. Three problems:

• No revocation granularity — revoking the key kills every agent using it.
• No spend cap — the agent can drain a budget in seconds.
• No audit trail per delegation — when something goes wrong, the audit log shows "the API key did it" rather than "this agent run did it."

Delegation tokens fix all three by binding authority to a specific agent run with explicit limits, an explicit TTL, and an explicit revocation path.

See also

• How it works — pipeline stages.
• Authorization Boundary — where delegation is enforced.
• Receipts — what gets recorded.