Skip to main content

API keys

API keys let a script or another system call the Regen API on behalf of your workspace, without a person signing in. Typical uses are opening an incident from a deploy pipeline, or reading alerts into your own reporting.

This page covers creating and using keys. An endpoint-by-endpoint reference is not published yet.

Who can manage keys​

Only workspace admins and owners can create, list or revoke keys. They are managed under API Keys in the left-hand menu.

Anyone who has a valid key can use it, so treat a key like a password.

Create a key​

  1. Open API Keys and choose to create a key.
  2. Give it a name that says what uses it, for example deploy-pipeline.
  3. Choose its scopes (see below).
  4. Optionally set an expiry date. Without one, the key never expires.
  5. Copy the key straight away.

The full key is shown once. Regen stores only a hash of it, so it cannot be shown again. If you lose it, revoke it and create another.

If you have two-factor authentication turned on for your own account, creating or revoking a key asks you for a code from your authenticator first.

Keys start with regen_live_. The key list shows the beginning of each key so you can tell them apart, along with when it was last used and when it expires.

Use a key​

Send the key as a bearer token in the Authorization header. The key identifies your workspace, so you do not need to include a workspace name.

curl https://regen.fluidify.ai/api/v1/incidents \
  -H "Authorization: Bearer regen_live_xxxxxxxxxxxxxxxx"

A request with a missing, revoked or expired key gets 401 Unauthorized. The response is the same in each case, so it does not reveal whether a given key exists.

Scopes​

A scope is a permission written as resource:action, for example incident:read or alert:acknowledge. A key can only do what its scopes allow, and a key can never do more than the person who created it. If that person is later given a lower role, the key is limited with them.

A request outside the key's scopes gets 403 Forbidden. A key created with no scopes can do nothing.

When you create a key, the form lists every scope you can give it. It is the full, current list, so check there rather than relying on a copy elsewhere. Scopes follow the same roles as people do: read scopes are at viewer level, scopes that change incidents are at responder level, and scopes that change configuration are at admin level. See Users, roles and teams.

Powerful scopes​

Some scopes are listed separately under "Powerful scopes: give these only to keys you fully trust", with a note on what they allow. They include:

  • user:manage: create, change and deactivate people. Needed for SCIM and identity-provider provisioning.
  • settings:write: change workspace settings.
  • integration:write: connect and change integrations.
  • custom_domain:write: change the workspace's custom domains.
  • team_membership:manage: add and remove people on any team.

Scopes a key can never have​

Some actions are deliberately kept for signed-in people, and cannot be given to a key:

  • Managing API keys. A leaked key can never create a broader one for itself.
  • Billing, and changing or deleting the workspace itself.
  • The one-off import wizards and the first-run setup wizard.

Give each key the fewest scopes it needs. A pipeline that opens incidents needs incident:write, not everything.

Revoke a key​

Revoke a key from the same page when it is no longer needed or may have leaked. It stops working straight away.

Good practice​

  • One key per system, named after it, so you know what to revoke if something leaks.
  • Set an expiry for anything temporary.
  • Keep keys in your secrets manager or CI secret store, never in source control.
  • Check the last used date now and then, and revoke keys nothing uses.