Authentication

The Agentagon SDKs accept three token shapes. They all go out as Authorization: Bearer <token>; the platform middleware dispatches based on the prefix.

Token shapes

Prefix	Name	Where it’s used	How to mint
`ag_pat_`	Personal Access Token	SDK clients, MCP servers, CI	`agentagon pat create` (buyer) or `agentagon service pat create` (seller)
`as_`	Account session	CLI (transient), dashboard	Returned by `agentagon init`; refreshed automatically
`ag_treasury_sk_`	Legacy master key	Pre-2026-04-27 deployments	Removed; reject in production

⚠️

Master keys are gone. ag_live_sk_* (seller) and ag_treasury_sk_* (Treasury) were hard-cut on 2026-04-27. The platform middleware returns 401 for any request bearing one. New code must use PATs or sessions.

PAT scopes

PATs carry a scope at mint time:

Service-scoped (pat_scope_type=service): authorized for a single seller’s management surface (transactions, verify, endpoints, ledger). Used by agentagon.seller, agentagon-mcp, and CI.
Agent-scoped (pat_scope_type=agent): authorized for a single buyer agent’s wallet operations (balance, pay, transfer). Used by agentagon.buyer, agentagon-buyer-mcp.
Treasury-scoped (pat_scope_type=treasury): authorized for direct Treasury operations (sub-wallets, signing). Used by agentagon.wallet.

Scopes are non-overlapping: a service-scoped PAT can’t sign payments, an agent-scoped PAT can’t read another service’s ledger.

Daily caps

Buyer PATs carry a daily_cap_usd (set at mint time, configurable via dashboard). Once daily spend hits the cap, the platform returns:

HTTP 429
{
  "error_code": "MGMT_6014",
  "user_message": "Today's spend cap on this PAT has been hit...",
  "recovery": {
    "kind": "raise_pat_cap",
    "settings_url": "https://app.agentagon.ai/account/settings",
    "current_cap_usd": "5.00",
    "attempted_amount_usd": "5.50"
  }
}

Surface recovery.user_message verbatim and deep-link settings_url. The cap resets at UTC midnight.

Recovery actions

The platform returns a structured recovery block on every agent-blocking error so headless agents can act without parsing prose. Canonical kinds:

`kind`	When	Useful fields
`fund_wallet`	Insufficient balance	`deposit_url`, `deposit_uri`, `shortfall_usd`, `chain`
`raise_pat_cap`	Daily cap exceeded	`settings_url`, `current_cap_usd`, `attempted_amount_usd`
`reauthenticate`	PAT revoked, session expired	`cli_command`, `login_command`
`raise_max_amount`	`max_price_usd` budget cap exceeded by seller’s price	`required_amount_usd`, `current_max_amount_usd`
`use_alternate_scheme`	No compatible accept	`offered_schemes`
`create_wallet`	No wallet on the requested chain	`chain`, `dashboard_url`

Branch on recovery.kind. Treat unknown kinds as no-recovery and re-raise.

Session refresh

The CLI’s account session (as_*) expires; on expiry, the CLI silently exchanges the active agent’s PAT for a fresh session via POST /v1/identity/exchange-pat. No user prompt unless the PAT itself is gone.

The SDKs do not auto-refresh on 401. They surface the error directly so the caller (a CLI, dashboard, or agent) decides whether to re-auth. This keeps the SDK stateless and predictable.