Skip to main content

​
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

Anything defined in the PagerDuty API 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 for details.
1

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

Open the API Access Keys page

Navigate to Integrations, then Developer Tools, and select API Access Keys.
3

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

Copy the key immediately

Click Create Key and copy the value right away, then click Close.
5

Double-check the account

If you operate more than one PagerDuty account, confirm you are in the correct account/subdomain before creating the key.
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.
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.

​
Connect in Serval

1

Start a new PagerDuty connection

In Serval, open the PagerDuty integration and start a new connection. The Configure PagerDuty dialog opens.
2

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

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

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.
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:”.
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.

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

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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, so an invalid path is caught when the workflow code is type-checked rather than at runtime.
Need help? Contact support@serval.com for assistance with your PagerDuty integration.