API keys

Every /v1 request authenticates with an API key: Authorization: Bearer sk_test_…

Every /v1 request authenticates with an API key: Authorization: Bearer sk_test_... (test) or sk_live_... (live). The key’s mode scopes all data — a test key never sees live resources, and vice-versa. Your organization’s first test + live pair is issued when you sign up in the dashboard; from there you mint and rotate keys through /v1/api_keys.

These routes are platform-scoped: the Invoice-Account header is not honored here (sending it returns 400 connect.not_supported_here). You manage keys with your own key, never on behalf of a connected account.

Create a key

The plaintext key is returned once, at creation. Store it immediately — it is never shown again (only a prefix for identification). mode is independent of the calling key, so a test key can mint a live key.

curl -sX POST $BASE/v1/api_keys \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{ "name": "server-side worker", "mode": "live" }'

{
  "object": "api_key",
  "id": "key_...",
  "name": "server-side worker",
  "mode": "live",
  "prefix": "sk_live_ab12",
  "key": "sk_live_...",      // the full secret — shown ONLY here
  "created_at": "2026-07-10T18:25:43Z",
  "revoked_at": null,
  "version": null
}

List, rename, pin a version

curl -s $BASE/v1/api_keys -H "authorization: Bearer $KEY"          # both modes; no secrets
curl -sX PATCH $BASE/v1/api_keys/key_123 -H "authorization: Bearer $KEY" \
  -H 'content-type: application/json' -d '{ "name": "renamed" }'

PATCH accepts name and/or version. A version is validated against the supported API-version registry (an unknown value returns 400 request.invalid_version); a pinned version applies to requests made with that key unless overridden by the Invoice-Version header. The list endpoint paginates with starting_after / ending_before.

Rotate and revoke

To rotate: create a replacement key, deploy it, then revoke the old one.

curl -sX DELETE $BASE/v1/api_keys/key_old -H "authorization: Bearer $KEY"

Revocation is a soft delete (sets revoked_at). A revoked key fails auth immediately with 401 auth.key_revoked — there is no grace period. If you revoke the last active key of a mode, the response includes a warning so you don’t lock yourself out.

Security notes

• Keys are stored only as a hash; the API can never show you an existing key’s secret.
• Treat sk_live_ keys as production secrets. Use separate keys per service so you can revoke one without disrupting the others.
• Every response carries a Request-Id; log it alongside key activity for auditing.