Copy page

Documentation

Agent identities

An agent identity is a delegated credential owned by a partner. It carries its own API ID and secret, a scope set, a budget, an approval threshold and optional expiry. Agent keys are for autonomous buying, not for account administration.

The main agent-management endpoints are in the published v1 OpenAPI document and served by the v1 API. PATCH /v1/agents/{agentId}/keys/{keyId} is in the schema and served by the v1 API. Budget enforcement is live: per-order, daily and rolling caps fail closed. Human approval above a threshold is Planned and returns approval_required today without an approval exchange.

Principal key vs agent key

An agent key that calls a management path gets 403 forbidden. The agents:manage scope is a principal scope even though the public manifest lists it among assignable scopes. Agent keys cannot receive it.

Scopes

Give an agent the smallest set that completes its job. A buying agent usually needs catalog:read, quotes:write, orders:read, orders:write, esims:redeem and wallet:read. Do not grant wallet:fund to an agent unless the principal explicitly delegates funding. Funding authority is not implied by an order scope.

Create an agent

Code
POST /v1/agents

Required scope: agents:manage. Principal only.

Code
{
  "name": "procurement-agent-eu",
  "purpose": "Buy connectivity for field staff in the EU",
  "scopes": ["catalog:read", "quotes:write", "orders:read", "orders:write", "esims:redeem", "wallet:read"],
  "perOrderLimitMinor": 5000,
  "dailyLimitMinor": 15000,
  "rollingLimitMinor": 25000,
  "approvalThresholdMinor": 1000,
  "expiresAt": "2027-02-01T00:00:00.000Z"
}

Amounts are minor units. The response is the public agent object with its id, status, scopes and limits. It never returns a secret.

Issue a key

Code
POST /v1/agents/{agentId}/keys

Code
{
  "name": "production",
  "ipAllowlist": ["203.0.113.0/24", "2001:db8:1234::/48"]
}

The response contains apiId, apiSecret, environment, scopes and a one-time notice. The secret is shown once. Store it immediately and never print it in logs, prompts, chat or client bundles.

Code
{
  "agentId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "apiId": "rw_sandbox_xxxxxxxxxxxx",
  "apiSecret": "REDACTED-ONE-TIME-SECRET",
  "environment": "sandbox",
  "scopes": ["catalog:read", "quotes:write", "orders:read", "orders:write", "esims:redeem", "wallet:read"],
  "notice": "Store apiSecret now. It cannot be retrieved again."
}

Manage keys

Code
PATCH /v1/agents/{agentId}/keys/{keyId}
POST  /v1/agents/{agentId}/keys/{keyId}/rotate

• PATCH updates the allowlist or sets revoked: true. The response returns the key metadata, never the secret.
• POST .../rotate issues a new API ID and secret. The old key expires after 24 hours. Update your secret manager before the window closes.
• A revoked key returns 401 unauthorized on the next request.
• Rotating a key does not change its scopes. Update the agent scopes first if the mandate changed.

Both paths require agents:manage and a principal key.

Read the current agent

Code
GET /v1/agents/me

Returns the calling agent's id, name, partner id, environment and scopes. It never returns a secret. A principal key returns 403 forbidden because it is not an agent.

Update and revoke

Code
PATCH  /v1/agents/{agentId}
DELETE /v1/agents/{agentId}

• PATCH updates scopes, any of the three limits, the approval threshold, or status (active, suspended, revoked).
• DELETE revokes the agent and every key attached to it.
• Changes take effect on the next request. There is no token cache to flush.
• An agent cannot edit itself. The API rejects an agent key on both paths.

Lifecycle

Code
create agent
    │
    ├── issue key ──> active ──> rotate ──> old key expires after 24h
    │                    │
    │                    ├── suspend ──> 401 agent_inactive
    │                    └── revoke  ──> 401 unauthorized on all keys
    │
    └── expiresAt reached ──> 401 agent_inactive

Agent status is checked on every authenticated request. A suspended, revoked or expired agent cannot call the API even if its key has not expired.

Budget enforcement

The agent record stores perOrderLimitMinor, dailyLimitMinor, rollingLimitMinor and approvalThresholdMinor. The current order handler does not yet enforce those values. Budget enforcement and human approval are Planned. Until they ship:

• The principal must set the mandate and enforce the budget in the calling system.
• The agent must check the quote or expected total against its mandate before ordering.
• The agent must stop above its approval threshold and ask the principal.
• Do not treat the presence of a stored limit as a server-side guarantee.

This gap is intentional and visible so no partner assumes a control that is not active. See Agent payment and Approval flow.

Security rules

• One agent per workload or purpose. Do not share an agent key between unrelated systems.
• Use a stable egress and an IP allowlist for live agents.
• Keep the secret server-side only. The API ID is public; the secret is not.
• Rotate on a schedule and immediately after any suspected exposure.
• Do not paste the secret into a prompt, ticket, dashboard note or chat.
• Report suspected exposure to [email protected].

Related

• Authentication for the signing string.
• IP allowlist for network controls.
• Agent payment for the buying flow.
• Approval flow for threshold decisions.