Skip to main content
Manage API keys for your organization. This API lets you create, view, 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 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 “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.