For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
WebsiteDashboardGet API key
  • Get Started
    • Welcome
    • Quickstart
    • Agent onboarding
    • Service keys
    • Core Concepts
  • Guides
    • Hosted Mode
    • Webhook Mode
    • Audio Mode
    • SMS and Conversations
    • Compliance and Consent
    • Billing and Usage
    • Voice zones
    • SMS zones
  • Reference
    • Authentication
    • API Overview
    • Errors and Testing
  • API Reference
  • Changelog
    • Cloudflare Insights CSP
    • Agent-native key management
    • Postpaid auto-charge
    • Cents-honest pricing
    • Stripe payments foundation
    • Hosted/webhook mode rename
    • Upgrading to v0.5.7.0
LogoLogo
WebsiteDashboardGet API key
On this page
  • What changed
  • New endpoints
  • New error codes
  • SDK updates
  • Next steps
Changelog

Agent-native key management

2026-05-13 · v0.5.7.0 · feature

Was this page helpful?
Previous

Postpaid auto-charge and low-balance modal

2026-05-06 · v0.5.5.0 · feature

Next
Built with
Headline. Service keys (sk_svc_…) can now mint, rotate, and revoke API keys via POST /v1/keys. Your agent manages its own credentials with full audit lineage.

v0.5.7.0 ships agent-native key management: a portal-bootstrapped service key (prefix sk_svc_…) can now mint, list, update, rotate, and revoke child API keys via POST /v1/keys. Existing sk_test_… and sk_live_… API keys keep working with no changes. There is nothing to migrate unless you opt in.

For the full concept page, see Service keys. To upgrade an existing integration, see the dedicated upgrade guide.

What changed

  • New credential type: service keys (sk_svc_test_… / sk_svc_live_…), generated from the portal, used for /v1/keys credential management. They authenticate the same way as regular API keys (Authorization: Bearer …) but cannot place calls, send SMS, or read /v1/audit.
  • Six new endpoints under /v1/keys for child key lifecycle, plus GET /v1/audit for the compliance event stream.
  • New Service Keys tab in the portal (Settings → Keys).
  • TypeScript, Python, and MCP SDKs all expose client.keys.{create,list,get,update,delete,rotate}.
  • Audit-of-audit: reading /v1/audit writes an audit_read compliance event.
  • Nine new compliance event types covering agent key and service key lifecycle.

New endpoints

MethodPathPurpose
POST/v1/keysMint a child API key. Requires Idempotency-Key.
GET/v1/keysList child API keys. Paginated.
GET/v1/keys/{id}Fetch one child API key. Returns the soft-revoked row even after DELETE.
PATCH/v1/keys/{id}Update name, label, line scope, cap, or permissions.
DELETE/v1/keys/{id}Soft-revoke. Effect is immediate, no grace window.
POST/v1/keys/{id}/rotateMint a new plaintext, revoke the old. Requires Idempotency-Key.
GET/v1/auditRead the compliance event stream. Uses a regular API key, not a service key. Writes an audit_read event on every read.

New error codes

CodeHTTPWhen
missing_idempotency_key400POST /v1/keys or rotate called without Idempotency-Key header.
idempotency_key_reused409Same idempotency key reused with a different body (same method+path) within the 12-hour cache window.
idempotency_in_progress409A prior request with this Idempotency-Key is still in-flight. Retry after about 1s.

Four envelopes from v0.5.6.0 are now also documented in the OpenAPI spec: agent_scope_error (403), agent_permission_denied (403), agent_cap_exceeded (402), and m3_fraud_block (403).

SDK updates

All three official clients gain a keys resource:

  • TypeScript (@saperly/sdk): client.keys.create / list / get / update / delete / rotate. Auto-generates Idempotency-Key (UUID v4) when one isn’t passed.
  • Python (saperly): same surface, snake_case (agent_label, line_id, monthly_cap_cents, idempotency_key). Sync and async clients.
  • MCP (@saperly/mcp): same surface as tools. Destructive tools (keys.delete, keys.rotate) require confirm: true in the tool call.

Next steps

  • Read the Service keys concept page
  • Follow the Agent onboarding quickstart
  • Step through the upgrade guide if you have an existing integration