# API keys ## What this builds Keys that the customers of an app create to call its API from their own code. A key is shown once, stored as a hash, checked on every API request, and can be given scopes, rotated and revoked. The app's routes ask one guard which key called. Read `spekkr.inputs.json` first. Every key starts with `key_prefix`. `owner` says whether a key belongs to a user or to a workspace. `scopes` decides whether R3 exists and `expiry` whether R6 does. This spec needs the app to know who is signed in on its pages, so that a person can manage keys. It does not build sign-in. ## Out of scope - OAuth and tokens that act for a person. - Rate limits per key. `spekkr/rate-limiting` adds them. - Billing by usage. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Create a key - A signed-in person creates a key with a name. With `owner` set to `workspace`, only people who may manage the workspace can. - The whole key is shown once, at creation, with a way to copy it. It can never be shown again. - Only a hash of the key's secret part is stored, with its last 4 characters for display. - An owner has at most 50 keys that are not revoked. Accept when: the key shown at creation authenticates, the database holds nothing the key could be rebuilt from, and the 51st key is refused with a clear message. ### R2. Authenticate a request - An API request sends the key as `Authorization: Bearer KEY`. A key in the query string is refused, even a valid one. - One guard, `require_api_key`, gives the route the key's owner and scopes, or answers 401 with a JSON error and a `WWW-Authenticate: Bearer` header. - A missing, malformed, unknown, revoked or expired key all get 401, each with its own short message. - The time and IP address of the last use are recorded, written at most once a minute per key. - After 20 failed attempts from one IP address inside a minute, that address gets 429 for the rest of the minute. Accept when: each kind of bad key gets its 401, a valid key reaches the route, and the key never appears in a log line or an error message. ### R3. Scopes Only if `scopes` is on. - Scopes are a fixed list in code. Start with `read` and `write`. - A key is created with one or more scopes, and each route names the one it needs. - A request whose key lacks the scope gets 403 with a message that names it. Accept when: a `read` key reads and gets 403 on a route that needs `write`, and a key cannot be created with a scope that is not in the list. ### R4. List and revoke - The keys page lists each key's name, its prefix and last 4 characters, scopes if they are on, when it was created, and when and from where it was last used. - Revoking a key takes effect on the next request. A revoked key stays in the list, marked revoked, for 30 days. Accept when: a revoked key gets 401 on its next request, and one owner never sees another owner's keys. ### R5. Rotate - Rotating a key creates a new key with the same name and scopes, and shows it once. - The person chooses how long the old key keeps working: not at all, 1 hour or 24 hours. After that it is revoked without anyone doing anything. - The list shows which key replaced which. Accept when: both keys work during the chosen time, and only the new one after it. ### R6. Expiry Only if `expiry` is on. - A key can be created with an expiry date, at least one hour ahead. - An expired key gets 401 with a message that says it has expired. - The list shows the date and marks keys that expire within 7 days. Accept when: a key works one second before its expiry and not one second after. ### R7. A route to try - `GET /api/v1/whoami` needs a key and answers with the owner's id, the key's name and its scopes. Accept when: the route answers with a valid key and with 401 without one. ### R8. Pages - The keys page, and a dialog for a new key that shows it once with a copy button and says it cannot be shown again. - Closing that dialog asks for confirmation. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - No test output or log line contains a whole key. - A README explains the key format, how to protect a route, and how to run the tests.