> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/pagerduty.md).

# PagerDuty

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

## Why use the integration for PagerDuty

PagerDuty is an incident response platform for managing alerts, on-call rotations, and escalation policies. The integration for PagerDuty syncs your PagerDuty services, on-call schedules, escalation policies, and incidents into Cortex, connecting each service's operational data to its ownership and metadata in your software catalog.

Instead of switching tools to answer "who is on call for this service?", you can see current on-call information on an entity's details page, view PagerDuty incidents in its event timeline, and trigger incidents without leaving Cortex. When an incident is triggered, the [On-call Assistant](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant.md) notifies users via Slack with runbooks, dependencies, and key information about the affected entity. Because PagerDuty data is available in CQL, you can also create Scorecards that enforce on-call standards at scale and track metrics like mean time to resolution (MTTR) in Eng Intelligence.

Integrating PagerDuty with Cortex allows you to:

* Pull in PagerDuty services, on-call schedules, and escalation policies. The on-call user or team appears in the **On-call** block on an entity's metadata sidebar, and on the entity's details page under **Connections > On-call**.
* Trigger incidents in PagerDuty directly from Cortex.
* Automatically surface vital information about entity health and metadata when an incident is triggered, using the On-call Assistant.
* View incidents from PagerDuty in an entity's event timeline.
* View on-call information from PagerDuty on the Engineering homepage.
* Use PagerDuty metrics in Eng Intelligence to gain insight into services, incident response, and more.
* Create Scorecards that track progress and drive alignment on projects involving your on-call schedules and alerts.

## Configuring PagerDuty

### Prerequisites

1. Users with the `Configure Integrations` permission can configure PagerDuty.

### Step 1: Creating an API key in PagerDuty

1. In PagerDuty, go to **Integrations > API Access Keys**.
2. [Create a PagerDuty API key](https://support.pagerduty.com/docs/generating-api-keys). 
   1. When adding the API key, you have the option to set read or write permissions:
      1. `Read-only` - Enables Cortex to read any and all data from PagerDuty
         1. If you create an API key with `Read-only` permissions, and you want to use the On-call Assistant in Slack, you also need to [configure a webhook](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant.md#configuring-a-webhook-for-read-only-api-keys) to get the Assistant working.
      2. `Write` - Allows users to trigger incidents from an entity page in Cortex, and enables the On-call Assistant
3. Copy the API key. Don't skip this step! You'll need the key to complete the setup.

#### A note about Scoped OAuth apps

If you registered a Scoped OAuth app in PagerDuty, you must also grant the following permissions:

* `incident.write` to create incidents
* `escalation_policies.write` to create escalation policies
* `schedules.write` to create schedules
* `services.write` to create services
* `teams.write` to create teams

### Step 2: Installing the PagerDuty integration in Cortex

1. From the main sidebar, select **Integrations**.
2. Locate PagerDuty, then click **Install**. The PagerDuty side panel opens.
3. In the PagerDuty side panel, do the following:
   1. From the **Category** dropdown, select at least one category that applies to the integration (required).
   2. Under **API key**, paste the API key you generated in PagerDuty (required).
   3. Optionally, toggle on **Read-only API key** if you created the key with read-only permissions.
4. Click **Test connection**. A successful connection means your integration is configured correctly.
5. Click **Save**.

{% hint style="info" %}
To modify an existing configuration, see [Modifying an integration configuration](https://docs.cortex.io/ingesting-data-into-cortex/integrations#modifying-an-integration-configuration).
{% endhint %}