Authentication
Last updated
Was this helpful?
Every request to /api/v1 (other than the public discovery endpoints /api/v1/openapi.json and /.well-known/agent-tools.json) requires an API key.
Admins create keys in the admin app under Settings → API Keys. Each key:
Is tenant-scoped — one key cannot operate across multiple tenants.
Carries one or more scopes: read, commerce, admin.
Has a rate-limit tier: standard, premium, unlimited.
Keys look like pk_<64 hex chars>. The plain-text value is shown only once at creation; only its SHA-256 hash is stored on disk.
Use either header on every request:
Authorization: Bearer pk_<your_key>…or:
X-API-Key: pk_<your_key>Both are equivalent. If both are present, Authorization wins.
Scopes nest:
So an admin key satisfies a commerce requirement, which satisfies a read requirement. Each endpoint declares the minimum scope it needs; this is shown on every reference page.
For example: reading the catalog or fetching a cart needs read; creating or modifying a cart, adding or removing items, and applying or clearing a promo code (the commerce surface) need commerce; managing API keys or webhooks needs admin. A read-only key receives 403 Forbidden on any commerce write.
401 Unauthorized
No key, unknown key, or revoked key
403 Forbidden
Key is valid but does not carry the required scope
Revoke a key from the admin app. Revocation takes effect immediately and is recorded in the audit log.
Never ship a key in client-side code.
Use the least-privilege scope. Read-only integrations should use read keys.
Rotate keys periodically. Issue a new key, switch your integration, then revoke the old one.
If a key may be exposed (e.g. logged accidentally), revoke it immediately and re-issue.
Last updated
Was this helpful?
Was this helpful?
admin ⊃ commerce ⊃ read{
"error": "Insufficient scope. Required: 'commerce'. Your key has: [read]."
}