> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# PagerDuty Integration

> Integrate PagerDuty with Aurora for incident management, on-call scheduling, and automated incident response

Connect Aurora with PagerDuty to receive incident webhooks, manage on-call rotations, and leverage AI-powered root cause analysis for faster incident resolution.

## Authentication

PagerDuty supports two authentication methods:

1. **API Token** (Recommended for development)
2. **OAuth 2.0** (Recommended for production)

### Option A: API Token

<Steps>
  <Step title="Create API Key">
    1. Go to [PagerDuty](https://app.pagerduty.com/)
    2. Navigate to **Integrations** > **API Access Keys**
    3. Click **Create New API Key**
    4. Select **Read** or **Write** permissions (both work)
    5. Copy the generated token
  </Step>

  <Step title="Connect to Aurora">
    1. In Aurora, go to **Integrations** > **PagerDuty**
    2. Paste your API token
    3. Click **Connect**
  </Step>
</Steps>

### Option B: OAuth 2.0

<Steps>
  <Step title="Create OAuth App">
    1. Go to [PagerDuty](https://app.pagerduty.com/)
    2. Navigate to **Integrations** > **Developer Mode** > **My Apps**
    3. Click **Create New App**
    4. Name: `Aurora`
    5. Enable **OAuth 2.0**
    6. Redirect URL: `http://localhost:5000/pagerduty/oauth/callback` (for development)
    7. Copy the **Client ID** and **Client Secret**
  </Step>

  <Step title="Configure Environment">
    Add to your `.env` file:

    ```bash .env theme={null}
    NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true
    PAGERDUTY_CLIENT_ID=your-client-id
    PAGERDUTY_CLIENT_SECRET=your-client-secret
    ```
  </Step>

  <Step title="Restart Services">
    Restart Aurora to apply the OAuth configuration:

    ```bash theme={null}
    make down && make dev
    ```
  </Step>

  <Step title="Connect via OAuth">
    1. In Aurora, go to **Integrations** > **PagerDuty**
    2. Click **Connect with OAuth**
    3. Authorize Aurora in the PagerDuty popup
  </Step>
</Steps>

## Configuration

### Environment Variables

```bash .env theme={null}
# Enable OAuth (optional)
NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true
PAGERDUTY_CLIENT_ID=your-client-id
PAGERDUTY_CLIENT_SECRET=your-client-secret

# For local webhook development
NGROK_URL=https://your-ngrok-url.ngrok-free.app
```

## Webhook Setup

Receive real-time incident notifications from PagerDuty (V3 webhooks only).

### Local Development Setup

<Steps>
  <Step title="Start Port Forwarding">
    PagerDuty webhooks cannot reach `localhost:5080` directly. Use ngrok:

    ```bash theme={null}
    ngrok http 5080
    ```

    Copy the HTTPS URL (e.g., `https://abc123.ngrok-free.app`)
  </Step>

  <Step title="Set Environment Variable">
    Add to `.env`:

    ```bash .env theme={null}
    NGROK_URL=https://abc123.ngrok-free.app
    ```

    Restart Aurora services:

    ```bash theme={null}
    make down && make dev
    ```
  </Step>

  <Step title="Get Webhook URL">
    In Aurora's PagerDuty integration page, copy your webhook URL:

    ```
    https://abc123.ngrok-free.app/pagerduty/webhook/{user_id}
    ```
  </Step>

  <Step title="Configure Webhook in PagerDuty">
    1. Go to [PagerDuty](https://app.pagerduty.com/)
    2. Navigate to **Integrations** > **Generic Webhooks (v3)** > **New Webhook**
    3. Paste the Aurora webhook URL
    4. Set scope to **Account** or specific services
    5. Subscribe to events:
       * `incident.triggered`
       * `incident.acknowledged`
       * `incident.resolved`
       * `incident.custom_field_values.updated`
    6. Click **Add Webhook**
    7. Send a test notification to verify
  </Step>
</Steps>

### Production Setup

In production, webhooks use your production backend URL automatically. No port forwarding needed.

Webhook URL format:

```
https://your-aurora-domain/pagerduty/webhook/{user_id}
```

## What Aurora Can Query

Once connected, Aurora can:

### Connection Status

* Verify token validity
* View connected user info
* Check account subdomain
* View token capabilities (read/write)

**API Endpoint:** `GET /pagerduty`

**Response:**

```json theme={null}
{
  "connected": true,
  "displayName": "PagerDuty",
  "authType": "api_token",
  "externalUserEmail": "user@example.com",
  "externalUserName": "John Doe",
  "accountSubdomain": "your-company",
  "capabilities": {
    "can_read_incidents": true,
    "can_write_incidents": true
  },
  "validatedAt": "2026-03-03T10:00:00Z"
}
```

### Webhook Events (V3 Only)

* Receive real-time incident events
* Auto-create Aurora incidents
* Track incident lifecycle (triggered, acknowledged, resolved)
* Monitor custom field updates
* Correlate related incidents
* Generate AI-powered root cause analysis

**Supported Events:**

* `incident.triggered` - New incident created
* `incident.acknowledged` - Incident acknowledged
* `incident.resolved` - Incident resolved
* `incident.custom_field_values.updated` - Custom fields changed

**Ingested Data:**

* Incident ID and title
* Incident status and urgency
* Service and escalation policy info
* Assignee information
* Custom field values
* Related alerts and context

<Warning>
  PagerDuty V1 and V2 webhooks are **not supported**. You must use V3 Generic Webhooks.
</Warning>

## Troubleshooting

**"PagerDuty OAuth is not enabled"**

* Set `NEXT_PUBLIC_ENABLE_PAGERDUTY_OAUTH=true` in `.env`
* Restart Aurora services

**"Missing OAuth credentials"**

* Verify `PAGERDUTY_CLIENT_ID` and `PAGERDUTY_CLIENT_SECRET` are set
* Check for typos in environment variable names

**"Unauthorized: Invalid or expired API token"**

* Verify token is correct and not revoked
* Check token has required permissions (Read or Write)
* For OAuth: token may have expired, reconnect

**Webhook Not Receiving Events**

* Verify `NGROK_URL` is set correctly (local development)
* Ensure ngrok/cloudflared tunnel is running
* Check webhook URL in PagerDuty matches Aurora UI
* Confirm webhook is subscribed to correct events
* Send test notification from PagerDuty
* Check Aurora logs for webhook errors

**"Account-level token" errors**

* Some account-level tokens cannot access user info
* Aurora will still work, but may not show user details
* Consider using a user-level token or OAuth

## API Reference

**Base Path:** `/pagerduty`

| Method | Endpoint             | Description             |
| ------ | -------------------- | ----------------------- |
| GET    | `/`                  | Check connection status |
| POST   | `/`                  | Connect with API token  |
| PATCH  | `/`                  | Rotate API token        |
| DELETE | `/`                  | Disconnect PagerDuty    |
| POST   | `/oauth/login`       | Initiate OAuth flow     |
| GET    | `/oauth/callback`    | OAuth callback handler  |
| POST   | `/webhook/{user_id}` | Receive V3 webhooks     |
| GET    | `/webhook-url`       | Get webhook URL         |

For detailed PagerDuty API documentation, see:

* [PagerDuty API Reference](https://developer.pagerduty.com/api-reference/)
* [PagerDuty Webhooks V3](https://developer.pagerduty.com/docs/webhooks/v3-overview/)