API keys

Control API access with account-level and team-scoped permissions.

Create and manage API keys from Settings → API keys.

Creating an API key

We’ll only show the API key token once at creation time, so store it somewhere safe.

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

Permission	What it allows	Team
View data viewer	Read-only access to public incidents and most organization settings.
View all incident data global_access	Adds read access to private incidents, alerts, and escalations.
Create incidents incident_creator	Open incidents and set fields, role assignments, timestamps, and attachments at creation.
Edit incidents incident_editor	Update, decline, merge, or cancel incidents, and manage calls and linked alerts.
Manage incident memberships incident_memberships_editor	View all incident data, including private incidents, and grant or revoke incident access.
Opt out of post-incident flow post_incident_flow_opt_out	Close an incident by opting it out of the post-incident flow.
Manage postmortems postmortems_manage	Manage postmortems, including updating their status and running imports.
Download investigation artifacts investigation_download	Download AI investigation artifacts attached to incidents.
View participant workload incident_workload_viewer	View participant-workload analytics (who’s been involved in how many incidents).
View private participant workload incident_workload_private_viewer	View participant-workload analytics, including for private incidents.

Catalog and teams

Permission	What it allows	Team
View catalog catalog_viewer	Read-only access to catalog types and entries.
Manage catalog catalog_editor	Create, edit, and delete catalog types and entries.	Yes
Manage team memberships team_memberships_manage	Update team memberships and edit catalog entries.

On-call, escalations, and notifications

Permission	What it allows	Team
Manage on-call resources on_call_editor	Full on-call surface: alerts, sources, routes, schema, schedules, escalations, and maintenance windows.	Yes
View on-call resources on_call_viewer	Read-only view of on-call resources like alerts, escalations, and schedules.
Create escalations escalation_creator	Create, respond to, and cancel escalations.	Yes
Manage notification methods notification_methods_manage	Configure the on-call paging provider, and users’ notification methods and rules.
View unredacted notification methods notification_methods_unredacted_viewer	View users’ notification methods, including unredacted phone numbers. Grant sparingly.

Schedules

Permission	What it allows	Team
Create and update schedules schedules_editor	Create, update, delete, and view schedules.	Yes
Read schedules schedules_reader	Read-only access to schedules.	Yes
Create schedule overrides schedule_overrides_editor	Create schedule overrides only, not the schedules themselves.	Yes

Workflows

Permission	What it allows	Team
Manage workflows workflows_editor	Create, update, delete, and view workflows.	Yes
Manage workflows that run on private incidents private_workflows_editor	Everything in workflows, plus workflows that run on private incidents.	Yes
Workflows on private escalations private_escalation_workflows_editor	Manage workflows that run on private escalations.

Status pages

Permission	What it allows	Team
Publish status pages status_page_publisher	Create status page incidents and maintenance windows, and publish updates.

Secrets

Permission	What it allows	Team
Manage secrets secrets_manage	View, create, update, rotate, delete, and reference secrets.	Yes
Use secrets secrets_use	View secret metadata and reference secrets.	Yes

Organization and security

Permission	What it allows	Team
Manage organization settings manage_settings	Change organization-level configuration such as custom fields, and manage the catalog.
Update security settings security_settings_editor	Update the organization’s security settings. Grant sparingly.

API keys and attribution

Permission	What it allows	Team
Manage API keys api_keys_manage	View, create, edit, delete, or rotate API keys. A key with this permission can create more keys, but only within its own access. Can’t be granted through the public API.	Yes
Act on behalf of users act_on_behalf_of_users	Attach the on-behalf-of header to attribute API actions to a specific user. Grants no actions on its own, so pair it with another permission. Availability depends on your plan.

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)

Users with only team-scoped permissions can create, edit, and delete keys within their team, but cannot manage keys belonging to other teams.

FAQs

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?

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?

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).