Creating an API key
API keys can have account-level permissions, team-scoped permissions, or a combination of both. This means teams can manage their own config via the API without risking changes to other teams’ resources. When you create a new API key, you choose which permissions it has. You can only grant permissions that you yourself have. If you only have team-level permissions, you’ll only be able to create keys with team-scoped permissions.Account-level permissions
Account-level permissions apply across your entire organization. These are the same permissions available when creating custom roles, such as creating incidents, managing workflows, or reading catalog data.Team-scoped permissions
Team-scoped permissions restrict what a key can do to resources owned by specific teams.Permissions reference
Each permission bundles a set of underlying API scopes, so you grant capabilities without assembling scopes by hand. In the create dialog, hover the scopes badge on a permission to see exactly what it includes. These are the same permissions used to build custom roles, so a key can never do more than a user with the equivalent role. You can only grant permissions you already hold; any you don’t have appear locked. A Team value of Yes means the permission can also be scoped to specific teams, restricting it to resources those teams own.Incidents and investigations
Catalog and teams
On-call, escalations, and notifications
Schedules
On-call pay
Workflows
Status pages
Secrets
Telemetry
Organization and security
API keys and attribution
Best practices
- Least privilege: grant only the permissions a key actually needs.
- One key per integration: makes it easy to rotate or revoke one without affecting others, and keeps audit trails clear.
- Rotate regularly: and immediately if a key may have been exposed.
- Review periodically: remove keys that are no longer in use.
Editing an API key
Existing API keys can be edited after creation. You can update the key’s name, add or remove account-level permissions, and add or remove team-scoped permissions. To edit a key, you need the same permissions required to manage it — see Permissions required below.Permissions required
To manage API keys, you need one of:- The account-level Manage API keys permission (via a base or custom role)
- The team-scoped Manage API keys permission (via a team role)
FAQs
What's the difference between a permission and a scope?
What's the difference between a permission and a scope?
A scope is a single, granular capability in the API. A permission bundles several scopes together into something
meaningful, like the Edit incidents permission. You choose permissions when creating a key, not individual
scopes. To see the scopes behind a permission, hover its scopes badge in the create dialog.
Can an API key be scoped to multiple teams?
Can an API key be scoped to multiple teams?
Yes. A key can be associated with multiple teams, but it will have the same set of team-scoped permissions across
all of them.
Can a key have both global and team-scoped permissions?
Can a key have both global and team-scoped permissions?
Yes. A single key can have account-level permissions (e.g., read catalog data) alongside team-scoped permissions
(e.g., manage schedules for a specific team).