Skip to main content
Manage API keys for your organization. This API lets you view, create, update, delete, and rotate API keys programmatically, including configuring account-level roles and roles scoped to specific teams. Common use cases include:
  • API key rotation: You can issue a new access token for any API key using the Rotate endpoint.
  • Managing keys at scale: use the Show, List, Create, Update, and Delete endpoints to automate API key lifecycle management.

​
Permissions model

To use these endpoints, your API key must have the api_keys_manage role granted at either the account level or for specific teams. In addition, the following rules apply, when a “caller” API key is managing a “target” API key:
  • A caller key can only assign roles whose scopes are a subset of its own scopes. For example, a key with viewer and incident_creator can assign those roles to a target key, but cannot assign the incident_editor role, since it has additional scopes.
  • The same applies at the team level: A caller key with schedules_editor at the account level can create a target key with that role for a specific team, but a key with schedules_editor only for one team (Team A, say) cannot assign it at the account level or for another team, Team B.
  • The api_keys_manage role cannot be assigned via the API. To create a key with that role, you must go to Settings → API keys in the dashboard, and click “Add new”, creating a key with the “View, create, edit, delete or rotate API keys” role (api_keys_manage).
  • The Delete endpoint does not check whether the calling API key holds the scopes of the key being deleted. However, a team-scoped key can only delete keys belonging to its teams.
  • To rotate the token of an API key, use the Rotate endpoint or by clicking “Rotate token” on any API key listed in the dashboard. The same permissions limitations apply as when creating or updating an API key.

​
Finding role names and team IDs

To find valid values for role_names, team_ids, and team_role_names, go to Settings → API keys in the dashboard. Click to either edit an existing key or create a new one, select the desired roles and teams, and then use the copy button to get hold of the role and team identifiers as JSON.

​
The api key object

​
created_at
string<date-time>
required

When the API key was created

Example:

"2021-08-17T13:28:57.801578Z"

​
creator
object
required
Example:
{
  "api_key": {
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "name": "My test API key"
  },
  "user": {
    "email": "lisa@incident.io",
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "name": "Lisa Karlin Curtis",
    "role": "viewer",
    "slack_user_id": "U02AYNF2XJM"
  }
}
​
id
string
required

Unique identifier for this API key

Example:

"01FCNDV6P870EA6S7TK1DSYDG0"

​
name
string
required

The name of the API key, for the user's reference

Example:

"My test API key"

​
roles
object[]
required

The account-level roles assigned to this API key

Example:
[
  {
    "description": "can view data, like public incidents and organization settings",
    "name": "viewer"
  }
]
​
team_ids
string[]
required

IDs of teams that this API key is scoped to

Example:
["abc123"]
​
team_roles
object[]
required

The team-level roles assigned to this API key

Example:
[
  {
    "description": "can view data, like public incidents and organization settings",
    "name": "schedules_editor"
  }
]
​
token_last_issued_at
string<date-time>
required

When the current token for this API was last issued. This is the last time the token was rotated, or when it was initially created. Older tokens may remain valid for up to an hour after they have been rotated, configured when you call the rotate endpoint.

Example:

"2021-08-17T13:28:57.801578Z"

​
last_used_at
string<date-time>

When the key was last used to authenticate a request

Example:

"2021-08-17T13:28:57.801578Z"