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

# PagerDuty

> PagerDuty is an incident response and on-call management platform - connect it to Serval so workflows can read and act on incidents, on-call schedules, and services through the PagerDuty REST API.

## About PagerDuty

PagerDuty is an incident response and on-call management platform that helps teams detect, triage, and resolve critical issues. The Serval integration stores a PagerDuty REST API key for your account and lets workflows call any part of the PagerDuty REST API with authentication handled for you - workflow authors never see or handle the key. You can connect multiple PagerDuty accounts to the same team, each as its own connection.

**Authentication:** a PagerDuty REST API key. A General Access REST API key (account-level) is the standard choice; a User Token REST API key also works but is limited to that one user's permissions. The key is stored encrypted and attached automatically to every request - and Serval only ever sends it to PagerDuty's own API host, api.pagerduty.com.

**Data sync:** on demand. There is no background sync - Serval calls PagerDuty only when a workflow runs.

## What the PagerDuty integration enables

| Capability                        | Description                                                                                                                                           |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full API access                   | A single "PagerDuty API request" workflow action can reach any part of the PagerDuty REST API, with the API key injected automatically on every call. |
| Incident management               | Read, create, and update incidents, incident notes, and log entries.                                                                                  |
| On-call and scheduling data       | Look up who is currently on call, plus schedules, escalation policies, and teams.                                                                     |
| Services, users, and account data | List and inspect services, business services, users, tags, audit records, automation actions, alert grouping settings, add-ons, and analytics.        |
| Multiple instances                | Connect more than one PagerDuty account, told apart by the auto-discovered subdomain and an optional Instance Name.                                   |

Anything defined in the [PagerDuty API](https://developer.pagerduty.com/api-reference/) can be accessed through Serval.

## Get your credentials

You need a PagerDuty REST API key. PagerDuty offers two kinds that both work with Serval: a **General Access REST API key** (account-level - recommended) and a **User Token REST API key** (tied to one person and restricted to their permissions). See PagerDuty's guide to [API Access Keys](https://support.pagerduty.com/main/docs/api-access-keys) for details.

<Steps>
  <Step title="Sign in with the right permissions">
    Sign in to the PagerDuty web app as an Admin or the Account Owner - only those roles can create General Access REST API keys. (User Token keys can be created from your own profile, but only on accounts with PagerDuty's Advanced Permissions.)
  </Step>

  <Step title="Open the API Access Keys page">
    Navigate to **Integrations**, then **Developer Tools**, and select **API Access Keys**.
  </Step>

  <Step title="Create the key">
    Click **Create New API Key** and enter a **Description** that identifies it later, for example "Serval Production Integration". Leave **Read-only API Key** unchecked if your workflows will create or update anything in PagerDuty - a read-only key can only read data.
  </Step>

  <Step title="Copy the key immediately">
    Click **Create Key** and copy the value right away, then click **Close**.
  </Step>

  <Step title="Double-check the account">
    If you operate more than one PagerDuty account, confirm you are in the correct account/subdomain before creating the key.
  </Step>
</Steps>

<Warning>
  PagerDuty shows the key in full only once, at creation time. If you lose it, you cannot retrieve it - delete the key in PagerDuty and create a new one.
</Warning>

<Note>
  The key must at minimum be able to read your account's teams - Serval validates the key by listing teams when you connect - and it needs read/write access matching whatever your workflows will do. Your PagerDuty account must contain at least one team the key can see.
</Note>

## Connect in Serval

<Steps>
  <Step title="Start a new PagerDuty connection">
    In Serval, open the PagerDuty integration and start a new connection. The **Configure PagerDuty** dialog opens.
  </Step>

  <Step title="Optionally name the instance">
    Fill in **Instance Name (optional)**. The form describes it as: "A name to distinguish between different PagerDuty instances (e.g., 'Production PagerDuty')". If you leave it blank, the connection is named after your PagerDuty subdomain, which Serval discovers automatically.
  </Step>

  <Step title="Paste your API key">
    Paste the key into **API Key** (shown as a password field). The form does not flag this field as required, so there is no inline prompt if you forget it - an empty submission simply fails with the install error described in the gotchas below.
  </Step>

  <Step title="Submit">
    Click **Submit**. Serval validates the key by reading your account's team list and derives your PagerDuty subdomain from the first team's web address. The subdomain identifies the connection (and names it, if you left Instance Name blank). If validation fails you will see "Failed to install integration (HTTP 500)" - see the gotchas below for what that usually means.
  </Step>
</Steps>

**Editing an existing connection:** the saved key is shown as a locked, masked value - bullets plus its last 4 characters - with a **Replace** button next to it. Leaving it untouched keeps your stored key; this is safe and verified, and the same is true if you click **Replace** but submit with the field empty. Enter a new key only if you intend to rotate or replace it. The **Instance Name** field comes pre-filled with the current name - typing a new name renames the connection, but clearing it to blank keeps the existing name rather than resetting it. Failed updates show an error toast reading "Failed to update integration:".

<Warning>
  Entering a new API key on update re-derives the subdomain from that key. Pasting a key from a different PagerDuty account silently re-points the connection at that account.
</Warning>

## Verifying the connection

PagerDuty connections don't currently include built-in health checks, so you won't see a health-check panel on this connection the way you do for some other integrations. The key is fully validated at connect time (Serval reads your team list), and you can confirm everything works after that:

* Check that the connection appears with the expected name - your Instance Name, or your PagerDuty subdomain if you left it blank. The subdomain should match the account the key came from.
* Run a workflow that reads PagerDuty data (for example, listing on-call responders) and confirm it returns results.

<Tip>
  If the connection looks healthy but specific workflow calls fail with permission errors, you are probably using a User Token key rather than a General Access key - user tokens are restricted to that one user's permissions and return a 403 for anything else. Switch to a General Access REST API key, or grant the token's user the needed access.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Connecting fails with 'Failed to install integration (HTTP 500)'">
    The connect form gives no detail on failure. A generic failure at connect time almost always means one of: an invalid or revoked API key, an empty API Key field (the form does not catch this inline), or a PagerDuty account with no teams the key can read. Verify the key in PagerDuty and retry.
  </Accordion>

  <Accordion title="Your PagerDuty account must have at least one team">
    Serval validates the key by reading the account's team list and derives your subdomain from the first team. If the key returns an empty team list, the connection cannot be created (the underlying error is "no teams found", though the UI shows only the generic install failure). Create at least one team in PagerDuty, and make sure the key can see it.
  </Accordion>

  <Accordion title="Updating the API key re-points the connection">
    Whenever you supply a new key on update, Serval re-derives the subdomain from that key and records it as the connection's identity. A key from a different PagerDuty account moves the connection to that account without warning. Double-check which account a replacement key belongs to.
  </Accordion>

  <Accordion title="Leaving the masked API Key untouched on edit is safe">
    On the edit form the key shows as bullets plus its last 4 characters, with a Replace button. Leaving it untouched - or clicking Replace and submitting nothing - keeps the stored key unchanged; this behavior is verified safe. Only a non-empty new value replaces the key.
  </Accordion>

  <Accordion title="Read-only keys can connect but cannot write">
    A General Access key created with the Read-only API Key option connects successfully (Serval's validation only reads data), but any workflow step that creates or updates something in PagerDuty will be rejected. Use a full-access key if workflows need to act on incidents.
  </Accordion>

  <Accordion title="Notes for workflow builders">
    PagerDuty results are paginated with offset-based paging, and Serval ships no PagerDuty-specific pagination helpers - workflows must loop through pages themselves, typically 100 records at a time. Requests are typed against [PagerDuty's official API schema](https://github.com/PagerDuty/api-schema), so an invalid path is caught when the workflow code is type-checked rather than at runtime.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your PagerDuty integration.