Skip to content
Round RobinRound Robin

Authenticating with an API key

A team API key is a long-lived credential that belongs to a Slack workspace rather than to a person. It carries only what it was granted at creation, and it does not inherit the access of whoever is signed in.

You need: a key. Create one in the dashboard under Settings → API keys, and see Creating and managing API keys for what each choice means.

Send the key

Section titled “Send the key”

Every /v1 request carries the key as a bearer token:

Terminal window
curl https://api.roundrobinbot.eu/v1/rotations \
  -H "Authorization: Bearer rr_live_..."

There is no other way in. Keys are not accepted in a query string, where they would land in every access log and browser history between you and us.

A key looks like rr_live_ followed by 32 characters. The prefix is there so a key that escapes into a repository, a log or a support thread is recognisable as a Round Robin credential at a glance, by us and by secret scanners. Keys issued against our development environment start with rr_dev_ and will not authenticate against api.roundrobinbot.eu.

Keep it secret

Section titled “Keep it secret”

The token is shown to you exactly once, when the key is created. We store only a hash of it, so nobody at Round Robin can read it back to you: a lost key is replaced, not recovered.

  • Put it in your platform’s secret store or CI secret, never in source control.
  • Give each integration its own key. Then a key can be switched off without taking the others down, and the last-used timestamp tells you what is still running.
  • Scope it to the rotations it actually needs, so a leak is bounded. See Scopes and access.

When a key stops working

Section titled “When a key stops working”

A refused request answers 401 with a JSON body that says which of several very different things went wrong, and names the key where we know which one it is. That id is the handle you can quote to us and read back in the dashboard; the secret never appears, in either direction.

{
  "status": 401,
  "title": "This API key is disabled",
  "detail": "The key exists but is switched off, which a workspace admin can undo. A key is also disabled automatically when the person who owns it leaves the workspace.",
  "code": "disabled",
  "keyId": "6a2f…"
}
code What happened What to do
missing_credential No key was presented: no Authorization header, or one carrying something that is not a Round Robin key Send the header. A dashboard session token is not accepted here.
unknown No key matches the token. A revoked key answers this too: revocation destroys the key’s secrets, so there is nothing left to recognise the token by Check the whole token was copied, and that it belongs to this environment. If the key was revoked, create a new one
disabled The key exists and is switched off Recoverable: a workspace admin can switch it back on
expired_secret The key works, but this is its previous secret and the grace period after a rotation is over Use the secret the rotation issued

401 responses also carry a WWW-Authenticate: Bearer challenge, so generic HTTP clients behave sensibly.

Replacing a secret

Section titled “Replacing a secret”

A key can hold two secrets at once, so replacing one needs no maintenance window: the new secret works immediately while the outgoing one keeps working for a grace period, and the key keeps its id, its scopes and its history throughout. expired_secret refers to an outgoing secret whose grace period has ended, on a key that otherwise works.

Rotate a key from the dashboard, under Settings → API keys. If a secret has leaked, rotate it with the option that kills the old one immediately, and do it without waiting for a reply from anyone else. See Creating and managing API keys.

Next steps

Section titled “Next steps”