Organization API Keys
Org-admin-issued machine credentials with granular permissions, environment scoping, and a lifetime cap, separate from personal API Access keys.
What it is
The API Keys screen lives in your organization’s admin area. It is where an organization admin issues the credentials that machines use — a CI pipeline, a scheduled job, a back-end service. Keys issued here belong to the organization as a whole rather than to one environment or one person, and each one carries an explicit set of permissions so a service gets only what it actually needs.
API keys are included with the Team plan and above. On a lower plan the screen explains that the organization authenticates people only, and no keys can be issued until the plan is upgraded.
Creating a key
Creating a key is an inline form on the same screen. You fill in four things:
- Name — required, up to 80 characters. This is the only way to tell keys apart once they are minted, so name it after the thing that will hold it, such as “Nightly reconciliation job” rather than “key 2”.
- Permissions — at least one is required. Each is a checkbox with a plain-language description of what it grants.
- Environment scope — Organization-wide by default, or one specific environment. Pinning a key to a single environment means a key meant for staging cannot touch production.
- Expires in (days) — leave it blank and the key never expires. If your organization’s access and security policy sets a maximum credential lifetime, an expiration becomes mandatory and is capped at that limit.
Permissions
| Permission | What it grants |
|---|---|
| Read | Reading rule sets, runs, and related data. |
| Write | Creating and changing rule sets and their contents. |
| Run | Executing rule sets. |
| Debug | Access to execution traces and debugging detail. |
| Admin | Administrative operations on the organization. |
| View PII | Seeing personal data unredacted rather than masked. |
Grant the smallest set that lets the integration do its job. A service that only needs to call a rule set and read the answer needs Run and Read, not Write or Admin. View PII in particular should be the exception: see Custom Roles & Access Review for how PII redaction works.
When a key is created, the full key is shown exactly once, in a banner asking you to copy it now. After you leave that banner only a short prefix is ever shown again, and there is no way to retrieve the full key later. Put it straight into your secret store — never into source control, a ticket, or client-side code. If you lose it, the only remedy is to revoke the key and create a new one.
Managing keys
The screen lists every key the organization has ever issued. Active keys come first; keys that have been revoked or have passed their expiration date are grouped separately under No longer usable, so the history stays visible without cluttering the list you actually act on.
Each key shows:
- Name and status — active, revoked, or expired.
- Key prefix — a short leading fragment, never the full secret.
- Permissions, as chips.
- Environment scope, or Organization-wide.
- Created date and who created it.
- Last used date, or Never used.
- Expiration date, or No expiry.
- Revoked date, if the key has been revoked.
The prefix and the last-used date are what make the list useful in practice: together they tell you which entry in your secret store a key corresponds to, and whether anything is still calling with it before you take it away.
Revoking a key
Revoking is immediate and irreversible. A confirmation dialog spells out what happens: the key stops working the next time it is used, and it cannot be reissued. Anything still holding that key starts failing, so revoke deliberately.
There is no rotate or regenerate action. To rotate a credential, create the new key first, deploy it to whatever holds the old one, confirm the old key’s last-used date stops advancing, and only then revoke it. That order avoids an outage in the gap.
Issuing and revoking keys is recorded in the audit log, with who did it and when, so you can answer later questions about when a credential came into existence and when it went away.
No token exchange in the browser
There is deliberately no place on this screen to trade a key for a token. That step belongs to the machine or service holding the key — a build agent, a server, a scheduled job — not to a person clicking through the app. If you find yourself wanting to do it by hand in the browser, the credential you want is probably a personal one rather than a machine one.
API Keys vs. API Access
The product has two separate ways to issue a key, and they are not the same screen. This page covers the organization-level API Keys screen. The older API Access screen lives inside an environment’s settings and issues keys of its own.
| Organization API Keys | API Access | |
|---|---|---|
| Where you find it | Organization admin area | An environment’s API Access screen |
| Availability | Team plan and above | Any plan, with an administrator role on the environment |
| Scoping | Organization-wide, or one environment | Organization, project, or a single rule set |
| What it can do | Chosen per key from Read, Write, Run, Debug, Admin, and View PII | Bounded by the key’s scope |
| Lifetime | Optional expiry, forced and capped when a credential lifetime policy is set | Optional expiration date |
Reach for Organization API Keys when you are provisioning a machine or service credential that belongs to the organization rather than to a person, when you want fine-grained permissions on it, or when a credential lifetime cap has to apply. Reach for API Access when you want a key bound tightly to one project or one rule set, which is the narrower scoping this screen does not offer.
Both kinds of key authenticate calls to the engine, and both are shown in full only once. Whichever you use, store it as a secret and rotate it by issuing a replacement.