Authentication
One header, one key, one account. What a key is, where it may live and how it is refused.
The header
Every request to /v1 carries a key as a bearer token.
A session cookie or an immit account token is refused on /v1. Only a key authenticates, and a key authenticates nothing else: it can reach no page, no setting and no flashcard of the account that holds it.
What a key is
A key is a credential on your developer account and nothing more. The tier, the quota and the burst are the account's, shared by every key of it: two apps on two keys share what the tier sells. Make as many keys as you have things that hold one, name each after that thing, and revoke the ones you stop using.
A key starts with ik_live_ and is followed by forty-three URL-safe characters. The console shows the first twelve, enough to tell keys apart. There is no test-mode key; the free tier is the sandbox.
Rotating a key
Create a new key, move your clients to it, then revoke the old one. Revoking never touches the plan, since the subscription hangs on the account and not on the key. A revoked key keeps its row and its usage in the console so the history stays whole.
Where a key may live
On a server, in a CLI, in a worker, in an agent that runs on your machine. /v1 answers any origin with the Authorization header allowed, so a page can call it directly, which is exactly why a key in a page is a key leaked.
How a key is refused
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | No bearer at all, or a bearer that is not a key. |
| 401 | api_key_invalid | A well-formed ik_live_ bearer that immit never issued. A typo reads as this, not as a generic 401. |
| 401 | api_key_revoked | The key was revoked from the console. |
| 401 | api_key_suspended | A person at immit suspended the key, after an email. |
Checking a key
GET /v1/me returns the key's name, the account's tier and quota, and today's usage. It is the call to make from a deploy script, and it counts like any other.