API keys

Reference article: Part of the API reference. How keys authenticate requests is covered in Authentication.

API keys live on the Developers page in Nimbus. From there you create keys, choose which workstreams they reach, reveal and copy them, roll them, rename them, and revoke them. The same page shows request metrics and logs for every key.

Who can manage keys: organization Admins and Global Admins. Members and guests don't see the Developers page. See Organization members and roles.

Creating a key

1. In the sidebar, open Developers.
2. Under API keys, click Create key.
3. Give the key a name that says where it runs, such as Production backend or CI status bot.
4. Choose the type:
   • Secret key: every resource, in the workstreams you give it.
   • Restricted key only has the access you choose. For each resource, pick None, Read, or Write.
5. Choose the workstreams the key can reach. See Workstream access.
6. Click Create key, then copy the key and store it in your secret manager.

Example scenario

Your team wants CI to post build results to the Releases workstream. An admin creates a restricted key named CI status bot with Write on Messages and nothing else, gives it the Releases workstream only, and stores it as a CI secret. If the CI system is ever compromised, the key can only post messages, only in that one workstream, and rolling it takes one click.

Workstream access {#workstream-access}

Scopes say what a key can do; workstream access says where. A key reaches only:

• the workstreams it has been granted, and
• the workstreams it created itself through the API.

Every other workstream, and everything in it, such as its messages, runs, and decisions, is invisible to the key. Requests for them fail with 404 resource_missing, as if they didn't exist.

To grant workstreams:

• When you create a key, choose its workstreams in the Create key dialog.
• Later, open the key's ⋯ menu and choose Workstream access…, then add or remove workstreams.

You can only grant workstreams you can open yourself. If a key already has workstreams you can't open, granted by another admin, your changes leave those grants as they are.

Rolling a key carries its workstream access over to the new key, so you don't need to grant anything again.

Revealing and copying a key

Click the eye icon next to a key to show it, and the copy icon to copy it. Copying a hidden key reveals it first. A revealed key hides itself again after a minute.

Every reveal is recorded in your organization's audit log, with who revealed which key and when.

Note: Keys are stored encrypted, so admins can reveal them later. If a key shows no eye or copy icon, no recoverable copy exists; roll it to get a new one.

Rolling a key

Rolling replaces a key's secret without changing its name, scopes, or workstream access. Use it on a schedule, when someone with access leaves, or when a key may have leaked.

1. Open the key's ⋯ menu and choose Roll key….
2. Choose when the current key stops working: Now, In 1 hour, In 24 hours, In 3 days, or In 7 days.
3. Click Roll key and copy the new secret.

With a grace period, both keys work until it ends, so you can deploy the new key without downtime. The old key shows Expires in … until then. With Now, the old key is revoked immediately; use this when a key may have leaked.

Renaming a key

Open the key's ⋯ menu and choose Rename…. The name only labels the key on the Developers page and in logs; renaming doesn't change the secret.

Revoking a key

Open the key's ⋯ menu, choose Revoke key…, and confirm. Requests with the key fail with api_key_revoked from then on. Revoking can't be undone: create or roll a key to restore access.

Revoked and expired keys are hidden by default. Turn on Show revoked and expired to see them.

Key status

FAQ

How many keys can we have?

There's no fixed limit. Create one key per integration, so each can be rolled or revoked without affecting the others.

Can I change a restricted key's scopes?

Not in place. Create a new key with the scopes you need, deploy it, then revoke the old one. Workstream access is different: change it any time from the key's ⋯ menu, under Workstream access….

Who can see a key's secret?

Organization admins, by revealing it on the Developers page. Every reveal is recorded in the audit log with who revealed it and when.

What happens to keys when the admin who created them leaves?

Nothing. Keys belong to the organization, not the person, so they keep working. Roll any keys that person had access to if you want to be sure they can't use them.

Does rolling a key change its ID?

Yes. The new key gets a new ID and the old one keeps its own, so the request log can still tell which one each request used. On the Developers page they share the same name.