API keys: use the API
An API key lets a program call the API as your account: Terraform, a script, your CI. A key belongs to the account, not to the person who made it: it keeps working when that person leaves, and every owner can see it, roll it and revoke it.
Only owners create, roll and revoke keys (Settings → API keys). A member’s sidebar does not list the page; it says Owners manage API keys and the audit log. Opened by its address, the page names the owners to ask.
Create a key
Section titled “Create a key”Settings → API keys → Create API key. Give it a name that says what will use it
(terraform-prod, ci-nightly: letters, numbers, dashes and underscores, up to 63 characters), choose
its access, and when it expires: 1 week, 1 month, 3 months (the default), 6 months, 1 year, or no
expiry. A key that never expires is the one still working years after it leaks, so prefer an expiry
and roll the key.
The key is shown once. Copy it into your secrets manager, tick “I have stored this key somewhere safe”, and close the dialog. We keep only a fingerprint of it and cannot show it again. If the dialog says the key was created but its secret can’t be shown (a retried request whose first answer was lost), revoke that key and create another.
An account has at most 50 live keys.
Read only, or full
Section titled “Read only, or full”| access | may call | may not |
|---|---|---|
| Read only | every GET a key may call: pipelines, their runs, alerts and notifications, sources, destinations, credentials’ hints, usage, notification settings and channels |
anything that changes something (403 api_key_read_only) |
| Full | everything a key may call: creating, starting, stopping and deleting pipelines; sources and credentials; and what only an owner may change for data: adding a destination, rotating a credential a destination uses, the account’s notification settings and channels, resends | people, money and keys (below) |
Neither can manage people, money or API keys (403 api_key_not_allowed): inviting or removing
people, changing roles, topping up the wallet, and creating, rolling or revoking keys need a person
signed in. A read-only key can read what the account’s API shows, addresses included (the account’s
notification address, who wrote a credential): treat any key as a secret.
A key’s access never changes. To change it, create a key with the access you want and revoke the old one.
Every time a full key uses owner power (adds or changes a destination, rotates a destination’s
credential, changes where notifications go, or copies a pipeline’s table again with
delete_rows_not_in_source: true, which deletes the destination rows the source no longer has), every
owner is emailed: the first change of a burst at once, the rest at most hourly, none left untold.
Call the API
Section titled “Call the API”Send the key in the Authorization header, from a server:
curl -H "Authorization: Bearer $REYANSH_API_KEY" https://<your app address>/v1/accountGET /v1/account answers which account the key acts for, and its access. Rules:
- Never put a key in a URL. A request with a key in its query string is refused
(
400 api_key_in_url), and the owners are told the key was exposed: roll it. - Only
https. A/v1request over plainhttpis refused (400 https_required), not redirected: anything it carried crossed the network unencrypted. If it carried a key, roll it. - Servers, not browsers. A key gives no access through a browser’s cookies, and a request carrying
both a key and a session cookie is refused (
400 credentials_ambiguous). Idempotency-Keyon every change. EveryPOST,PUT,PATCHandDELETEneeds one (a UUID per intended change). A retry with the same key and the same body replays the first answer instead of doing it twice. A key’s idempotency keys are its own and its rolled successor’s, so a retry after a roll may use the new key.- Treat the key as opaque, at most 255 characters. Today’s keys start
rsk_and matchrsk_[a-z2-7]{58}: add that pattern to your secret scanner.
Errors
Section titled “Errors”Every error is the standard envelope with a request_id. The ones a key meets:
| status | code |
what it means |
|---|---|---|
| 400 | https_required |
plain http to /v1: use https; roll the key if one was sent |
| 400 | api_key_in_url |
the key was in the URL: send it in Authorization, and roll it |
| 400 | authorization_invalid |
the Authorization header is not Bearer <key> (two headers, an empty one, a missing scheme) |
| 400 | credentials_ambiguous |
a key and a session cookie in one request: send one |
| 401 | unauthenticated |
no credential |
| 401 | authorization_scheme_unsupported |
a scheme other than Bearer |
| 401 | api_key_malformed |
not a key (a copy that lost a character, say) |
| 401 | api_key_invalid |
unknown or revoked |
| 401 | api_key_expired |
past its expiry (details.expired_at): create or roll a key |
| 403 | api_keys_not_enabled |
API keys are not switched on for this account yet |
| 403 | api_key_not_allowed |
people, money or keys: a person must do this |
| 403 | api_key_read_only |
a read-only key asked to change something |
| 429 | rate_limited |
over a limit below: wait Retry-After seconds |
Every 401 carries a WWW-Authenticate: Bearer realm="api" header.
Limits
Section titled “Limits”600 requests a minute per key, and 1,200 a minute across all of an account’s keys. Every key response
carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a refusal is 429 with
Retry-After. Repeated failed authentication from one address is limited too (a key that worked from
there in the last 10 minutes is never held up by it).
Roll a key
Section titled “Roll a key”Roll makes a new key with the same name and access, and keeps the old one working for as long as you choose: stop it now, 1 hour, 24 hours (the default), 7 days or 30 days. Move what uses it to the new key within that time. The old key’s row shows “rolling, stops at …” and its last used, so you can see whether anything still uses it. If something used the old key in its last 15 minutes, the owners are told it was still in use when it stopped; for an overlap longer than a day they are also told the day before.
The owners are emailed 7 days and 1 day before a key expires, and when it has. A rolled key gets no such email: rolling is the routine.
Revoke a key
Section titled “Revoke a key”A key’s row offers Revoke {name}…, which opens the dialog; the dialog’s button is Yes, revoke {name}, so a screen reader never hears two buttons with one name.
Revoke stops the key at once: every request made with it is refused from then on. The dialog first shows what the key built, which keeps running: the pipelines it created (each with Stop, or Stop its pipelines for all), the destinations and sources it created, the credentials it wrote, and the changes it made with owner power. Revoking is not undone; create a new key instead.
If a key leaks
Section titled “If a key leaks”- Revoke it (Settings → API keys → Revoke). If something important uses it, roll it with “Stop it now” instead, and put the new key in place.
- Read what it built, in the revoke dialog: stop the pipelines that should not run, and check the destinations it added or changed and the notification settings it changed.
- Read Key activity, the page’s Recent changes pane: every key created, rolled and revoked, every use of owner power, and every exposure the API saw.
Every owner is emailed when a key is created, rolled or revoked, when it uses owner power, and when it is exposed. Nobody can switch these emails off: they go to each owner’s own address.