Authentication
Every request carries an organization-scoped machine key as a bearer token. Keys are minted in the dashboard and can be limited by scope.
Keys
Mint a key in the dashboard under Settings → API Keys. Keys start with ak_ and are bound to your organization: everything a key creates or reads belongs to that organization and nothing else is visible through it.
Send the key as a bearer token on every request.
Authorization: Bearer ak_…Session tokens from the dashboard are not accepted on this API, and a key bound to a user rather than an organization is refused with 403 org_scoped_key_required.
Revocation and caching
Verification results are cached briefly, so revoking a key takes effect within about a minute rather than instantly. Plan changes are delayed the same way in reporting metadata, but never in enforcement: credit and subscription checks run live on every task, so a revoked plan cannot queue work during that minute.
Scopes
A key carries a list of scopes. Each route requires one of them:
| Scope | Grants |
|---|---|
products:read |
GET on products, imports and exports (including creating an export job, which writes nothing of yours) |
products:write |
Creating, updating and deleting products; submitting imports |
images:read, images:write |
Reading and uploading images |
tasks:read, tasks:write |
Reading and launching tasks |
webhooks:read, webhooks:write |
Managing webhook endpoints |
models:read |
Listing models |
A request outside the key’s scopes is refused with 403 insufficient_scope naming the scope it lacked.
Errors you will see
| Status | error.code |
Meaning |
|---|---|---|
401 |
missing_authorization |
No Authorization: Bearer … header |
401 |
invalid_token_type |
The token is not an ak_ machine key |
401 |
invalid_api_key |
The key is unknown, revoked or expired |
403 |
org_scoped_key_required |
The key belongs to a user, not an organization |
403 |
insufficient_scope |
The key lacks the scope this route needs |
Every response, including these, carries an X-Request-Id header. Quote it when you contact support.