Guide
Authentication
Every request carries an API key. The key decides which datasets and operations the request may reach.
Sending the key
Send the key in the Authorization header of every request, after the word Bearer.
Authorization: Bearer akq_live_7FB2QX0M4KAZ…Keep keys on a server. A key in a browser, a mobile app or a public repository can be copied and used by anyone.
Live and sandbox keys
| Key | Prefix | Reads |
|---|---|---|
| Live key | akq_live_ | Your organisation's published datasets: all of them, or the ones you choose. |
| Sandbox key | akq_test_ | The sample dataset only. Its requests are never counted against your quota. |
Owners and administrators create and revoke keys on the API page. The key is shown once, when it is created: store it as a secret.
A key can be limited to some datasets, to the rows or query operation, and given an expiry date. A revoked or expired key is refused on the next request.
When a key is refused
| Status | Code | Meaning |
|---|---|---|
401 | unauthenticated | No API key, or one that is unknown, revoked, expired or of a deactivated organisation. |
403 | operation_not_permitted | The API key is not scoped to this operation. |
404 | not_found | No such dataset, not published, or outside the key's datasets: one answer for all three. |
A dataset the key may not read is answered exactly as one that does not exist, so a key never learns what else is published.
Rate limits
Each key, and each organisation across its keys, has a burst allowance that refills continuously. A request past it is refused with 429 and the code rate_limited.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The burst of the rate-limit bucket that binds this request. |
X-RateLimit-Remaining | Requests left in that bucket after this one. |
X-RateLimit-Reset | Seconds until that bucket is full again. |
Retry-After | Seconds to wait before the next request would be served. |
Wait the seconds Retry-After gives, then try again. Rate limits protect the service; credits and quota are separate, on the credits page.
Correlation IDs
Every response carries X-Correlation-ID, and every error repeats it in its body. Quote it when you contact support.