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
If Veeton’s team gave you access to the API, mint a key in the dashboard: your profile picture at the top right → Organization → 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.
A key belonging to an organization that has not been given access to the API is refused with 403 api_access_not_enabled.
The API is available on paid plans only. A key belonging to an organization on a free trial, or without an active subscription, is refused with 403 plan_required on every route until the plan is upgraded; nothing about the key itself needs to change.
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 |
api_access_not_enabled |
The organization has not been given access to the API. Contact Veeton’s team. |
403 |
insufficient_scope |
The key lacks the scope this route needs |
403 |
plan_required |
The organization is on a free trial or has no active subscription. The API is available on paid plans. |
503 |
plan_lookup_failed |
Your subscription could not be read. Retry shortly. |
Every response, including these, carries an X-Request-Id header. Quote it when you contact support.