> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

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

Create and manage API keys from [**Settings → API keys**](https://app.incident.io/~/settings/api-keys).

## Creating an API key

<Warning>
  We'll only show the API key token once at creation time, so store it somewhere safe.
</Warning>

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](/admin/user-permissions#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](/admin/user-permissions#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](#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](/admin/user-permissions))
* The team-scoped **Manage API keys** permission (via a [team role](/admin/team-roles))

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

## FAQs

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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).
  </Accordion>
</AccordionGroup>