Skip to content

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.

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.

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.

Send the key in the Authorization header, from a server:

Terminal window
curl -H "Authorization: Bearer $REYANSH_API_KEY" https://<your app address>/v1/account

GET /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 /v1 request over plain http is 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-Key on every change. Every POST, PUT, PATCH and DELETE needs 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 match rsk_[a-z2-7]{58}: add that pattern to your secret scanner.

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.

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 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.

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.

  1. 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.
  2. 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.
  3. 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.