Authentication
Scoped API keys, and the limits around them
One header, two scopes, and limits you can read off every response. This page is the whole authentication contract — there is no OAuth dance and no token refresh to implement.
How do I authenticate with the Stackroom API?
Send your API key as Authorization: Bearer sk_live_…, or as an X-Api-Key header if that suits your client better. Keys are created per workspace in Settings → API keys, carry either the read or the write scope, and are checked against your plan on every request.
Keys
Getting a key and proving it works
Create a key in the console under Settings → API keys, choosing read or read-write at creation. The value is displayed once and stored hashed, so a lost key is replaced rather than recovered — and revoking one takes effect on the next request.
Before writing anything against it, call /ping. It returns the workspace the key belongs to and the scopes it carries, which is the fastest way to tell a wrong key from a wrong URL.
A 401 means the key is missing, wrong or revoked. A 403 on a read call means your plan no longer includes API access; on a write call it usually means the key is read-only.
# Either header works. Bearer is the conventional one.
curl -H "Authorization: Bearer sk_live_..." \
https://api.stackroom.io/api/v1/ping
curl -H "X-Api-Key: sk_live_..." \
https://api.stackroom.io/api/v1/pingLimits
Rate limits and quotas, on every response
Two limits apply. A per-minute rate limit in a fixed window, counted per key, and a monthly request quota counted in the database so it survives restarts. Both ceilings come from your plan.
You never have to infer either one: the headers on the right are on every response, including successful ones. Read X-RateLimit-Remaining and slow down before you are refused rather than after.
Exceed either and you get a 429 carrying Retry-After in seconds. Honour it — retrying immediately simply burns the rest of your window.
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1790000060
X-Quota-Limit: 100000 # or "unlimited"
X-Quota-Used: 4311
X-Quota-Remaining: 95689# A 429 tells you how long to wait. Honour it.
HTTP/1.1 429 Too Many Requests
Retry-After: 37
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Rate limit exceeded — 120 requests/min on the pro plan. Retry in 37s or upgrade for a higher limit."
}Errors
What each status means, and what to do
| Status | Meaning | What to do |
|---|---|---|
| 400 | Malformed request | A field failed validation. The message names it. |
| 401 | Invalid or missing API key | Check the Authorization header. A revoked key returns this too. |
| 403 | Read-only key, or plan gate | Create a key with the write scope, or check that your plan includes API access — the gate runs per request, not only at key creation. |
| 404 | No such record in this workspace | Ids are scoped to the workspace that owns the key. An id from another workspace is a 404, never someone else's data. |
| 429 | Rate limit or monthly quota exceeded | Read Retry-After and the X-RateLimit-* / X-Quota-* headers. Back off; do not retry in a tight loop. |
Errors share one shape — { statusCode, error, message } — and the message is written to be read by whoever is debugging, not just logged. Where a limit is involved it names the limit and the plan.
FAQ
Authentication questions
Where do I create an API key?
In the web console under Settings → API keys. You choose the scope at creation. The key is shown once and stored hashed, so if you lose it you issue a new one rather than recovering the old one.
What scopes are there?
Two: read and write. A read key can list and fetch; a write key can also create and update. Anything that changes data on a read key returns 403 with a message saying so, rather than failing silently.
Can one key reach more than one workspace?
No. A key is bound to the workspace that created it, and record ids are scoped to that workspace. An id belonging to another workspace returns 404 — never another tenant's data.
What are the rate limits?
Per key, per minute, with the ceiling set by your plan, plus a monthly request quota. Both are reported on every response in the X-RateLimit-* and X-Quota-* headers, so you can see where you stand without guessing.
What happens if my plan changes?
The plan gate runs on every request, not only when the key is created. If API access is dropped from your plan, existing keys start returning 403 immediately.
How should I store the key?
As a secret in your deployment environment, never in client-side code or a repository. Anything holding the key can read — and with a write scope, change — your whole register.
Ready to make the first call?
The API reference lists every endpoint with its parameters and an example you can paste into a terminal.