Authentication
One header, two kinds of credential, and why the capital letter matters.
Every request carries the same header:
Authorization: Bearer <token>The capital letter matters
The prefix is matched exactly as Bearer (capital B, one space). bearer
abc or BEARER abc are rejected as if you had sent nothing at all:
{ "error": { "code": "unauthorized", "message": "Missing or malformed Authorization header." } }It is the number one cause of a 401 on a credential that is perfectly valid.
Two token families
The prefix tells you what you are holding:
| Prefix | What it is | Acts as |
|---|---|---|
eel_sk_ |
A workspace API key | The workspace. There is no person behind it |
eel_at_ |
A connected app's access token | The person who authorized it |
eel_rt_ |
A connected app's refresh token | Nothing on its own. It only buys another eel_at_ |
The response shape never changes between them. What changes is which rows come back: a key sees what the workspace sees, a token sees what its person sees. That is covered in What each credential sees.
When it fails, and with what
| Situation | Code | Status |
|---|---|---|
| No header, or a malformed one | unauthorized |
401 |
| A token that does not exist, was revoked, or expired | unauthorized |
401 |
| A valid token missing the scope | forbidden |
403 |
| Too many requests | rate_limited |
429 |
A 403 on this API almost always means one thing: the credential lacks a scope, and the message names it.
What you will not see is a 403 for a record that exists but is not yours to read. That answers 404, indistinguishably from an invented id. See Shared rules.
Revocation takes up to a minute
A credential that has already been verified stays good for 60 seconds. Revoking a key, or letting one expire, can take that minute to take effect.
If you need access cut with certainty, revoke the credential and count that minute before treating the cut as done.