Skip to content
Round RobinRound Robin

Creating and managing API keys

An API key is the credential your own tools present to the Round Robin API. It belongs to the person who created it, carries only what they granted it, and lives in the dashboard under Settings → API keys.

You need: nothing beyond a Round Robin account. Anybody in the workspace can create a key, because a key can never do more than the person who created it. Admin rights only matter for a key covering every rotation, and for switching a disabled key back on.

Create a key

Section titled “Create a key”

Choose New key and answer three questions.

A name. How you will recognise this key in a year. Name the thing that uses it (“Nightly on-call report”, “Status page”) rather than yourself, because the owner is recorded separately and the point of the name is to tell two keys apart.

What it can do. The scopes it holds. Reading is always included. Add a write scope only when the integration actually writes.

What it can reach. Either every rotation in the workspace, including ones created later, or a list you pick. A key limited to named rotations answers as though the others do not exist, which keeps a leak bounded to the rotations you chose.

A key can never reach further than the person who created it. Only a workspace administrator can create one covering every rotation; anybody else picks from the rotations they are allowed to change, which is exactly what the dashboard offers them.

Then the secret appears, once.

The secret is shown once

Section titled “The secret is shown once”

We store a hash of the secret, not the secret, so nobody at Round Robin can read it back to you. If you lose it, you rotate the key and get a new one, which is quick but means redeploying whatever was using the old one.

Copy it into your platform’s secret store or CI secret before you close the dialog. The dialog will not let you dismiss it until you confirm you have, for exactly this reason.

What each key tells you

Section titled “What each key tells you”

The list gives you a row per key: its name, its owner, how far it reaches and when it was last used. Opening one shows the rest.

  • Who owns it and when it was created.
  • What it can do and reach, as granted at creation, with the rotations named rather than counted. Neither can be widened afterwards: a key that needs more is a new key.
  • When it was last used, or that it never has been. This is the field to read before retiring one: a key nothing has touched in months is a key nobody will miss.

Replace a secret without downtime

Section titled “Replace a secret without downtime”

Rotate secret issues a new secret and leaves the old one working for seven days. Both are accepted during that week, so you deploy the new one on your own schedule and nothing breaks in between. The key keeps its id, its scopes and its history throughout, so anything you wrote down about it stays true.

While a rotation is in flight, the key says so, and it says whether anything is still arriving on the old secret. That is the one number worth watching: traffic on the outgoing secret is a deployment that has not picked up the new one yet, and it will start failing when the week is up with an expired_secret refusal.

If a secret has leaked, choose Kill the old secret now instead. The old one stops being accepted immediately, and whatever is using it is down until you deploy the new one.

Switch a key off, or retire it for good

Section titled “Switch a key off, or retire it for good”

Disable stops the key answering and keeps its secret. Reach for it when a key is behaving oddly and you want it stopped while you work out why, because it can be switched back on.

Revoke destroys the key’s secrets. There is no way back: a revoked key answers unknown, as though it had never existed, and replacing it means creating a new key and deploying a new secret. Reach for it when the integration is gone for good.

Only a workspace administrator can switch a disabled key back on, and doing so gives the key a new owner and a new secret.

A revoked key stays on the page for 90 days, behind a Show revoked toggle under the list and with nothing left to act on, so a key that stopped working still has an explanation months later. After that the record is deleted, and the page says the date it will happen. The secret is gone from the moment you revoke, not from the moment the record is.

Keys stop when their owner leaves

Section titled “Keys stop when their owner leaves”

Every key belongs to the person who created it. When that person leaves the Slack workspace, their keys are switched off automatically and the workspace’s administrators are told which ones, by name. The integration stops rather than carrying on with the authority of somebody who is gone.

Nothing is lost: an administrator can switch the key back on, which makes it theirs and issues a new secret. Only the secret needs redeploying.

So an integration that matters to the whole team is better owned by somebody who is not about to change role, and giving each integration its own key means one person’s departure does not take everything down at once.

Limits

Section titled “Limits”

A workspace can hold 25 keys at a time. Disabled keys count towards that, because they can be switched back on; revoked ones do not, because they cannot.

Give each integration its own key rather than sharing one. Then a single key can be switched off without taking the others down, and the last-used timestamp tells you what is actually still running.

Next steps

Section titled “Next steps”