Auth and Error Model
Auth Schemes by Surface
Section titled “Auth Schemes by Surface”User bearer auth (Authorization: Bearer <user_access_or_privy_token>)
Section titled “User bearer auth (Authorization: Bearer <user_access_or_privy_token>)”Required for protected user routes:
/api/agents/*/api/users/*/api/billing/summary/api/billing/usage-summary/api/billing/checkout/api/billing/credits/checkout/api/billing/portal/api/billing/sync/api/billing/runtime-requests/api/billing/runtime-requests/:id/api/billing/runtime-requests/:id/approve/api/billing/runtime-requests/:id/deny/api/billing/runtime-spend-policies/:controllerAgentId/api/runtime/identities/api/runtime/delegations/api/runtime/delegations/:id/api/auth/device/approve
Runtime bearer auth (Authorization: Bearer <runtime_access_token>)
Section titled “Runtime bearer auth (Authorization: Bearer <runtime_access_token>)”Required for runtime-principal routes:
/api/runtime/auth/status/api/runtime/updates/manifest/api/runtime/updates/scripts/api/runtime/updates/check/api/runtime/updates/apply/api/runtime/updates/report/api/runtime/agents/:id/start/api/runtime/agents/:id/stop/api/runtime/agents/:id/status/api/runtime/billing/requests/api/runtime/billing/requests/:id/api/runtime/self/spend-policy
Gateway credential auth
Section titled “Gateway credential auth”Required for managed gateway routes. Credential may be passed as:
Authorization: Bearer <gateway_token>x-api-key: <gateway_token>
Applies to:
/api/gateway/llm/v1/chat/completions/api/gateway/llm/v1/responses/api/gateway/search/v1/web/search/api/gateway/search/v1/news/search
Webhook signature auth
Section titled “Webhook signature auth”For /api/webhooks/usage, signature may be required depending on deployment config:
- Header:
x-roberto-signature - Optional prefix accepted:
sha256=<hex>
Token Lifecycle Endpoints
Section titled “Token Lifecycle Endpoints”User token lifecycle:
POST /api/auth/device/startPOST /api/auth/device/pollPOST /api/auth/refreshPOST /api/auth/logout
Runtime token lifecycle:
POST /api/runtime/bootstrap/exchangePOST /api/runtime/auth/refreshPOST /api/runtime/auth/revokeGET /api/runtime/auth/status(runtime bearer token required)
Error Envelope
Section titled “Error Envelope”Most non-success responses use:
{ "error": "message" }Some endpoints add fields, for example device poll rate limiting:
{ "error": "slow_down", "retryAfterSeconds": 12}Common Status Codes
Section titled “Common Status Codes”| Status | Meaning | Typical causes |
|---|---|---|
400 | Invalid request payload/params | Missing required fields, invalid JSON, invalid query parameters |
401 | Auth failed | Missing or invalid bearer token, invalid gateway token, missing webhook signature |
402 | Billing restriction | Gateway access blocked by entitlement/billing state |
404 | Resource or token not found | Unknown agent/runtime/user code/session |
429 | Rate limited | Device poll flow or webhook ingest limits |
500 | Server config/runtime fault | Missing DB/auth secrets, unhandled server-side error |
503 | Dependency unavailable | Managed provider/config not available |
Operational Behaviors to Expect
Section titled “Operational Behaviors to Expect”- Authenticated CLI/MCP user calls typically retry once after refreshing tokens on
401. POST /api/auth/logoutis effectively idempotent for refresh-token revocation./api/webhooks/usagesupports idempotency withx-idempotency-key./api/runtime/updates/applyrequires bothapproved=trueand a valid one-time grant token.- Runtime bearer endpoints enforce live runtime identity state; revoked identities are rejected immediately.