PagerDuty

Trustle reads users, base roles, teams and their members, schedules, escalation policies, services, and on-call shifts from PagerDuty. Trustle can create and delete users, change base roles, and add and remove people on teams, schedules, and escalation policies.

Prerequisites

• A PagerDuty account with the Admin or Account Owner role. A key that another role creates cannot see or change every user and team.
• A PagerDuty account in the US region. Trustle sends every call to https://api.pagerduty.com. Contact Trustle support before you connect an account in the EU region.
• An identity provider connected in Trustle, for example Okta or Microsoft Entra ID. Trustle hides SaaS Applications until one is connected.

Configure PagerDuty

Step 1: Create a General Access API key

1. Sign in to PagerDuty as an Admin or Account Owner.
2. Go to Integrations → Developer Tools → API Access Keys. You can also open https://<subdomain>.pagerduty.com/integrations/api_keys directly.
3. Click Create New API Key.
4. Enter a description, for example Trustle.

Step 2: Grant permissions

A PagerDuty API key has no scopes. The key can do what its creator’s role can do, unless you make it read-only.

1. Leave Read-only API Key cleared.
2. Click Create Key.

Permission	Required	What Trustle does with it
Read access, from an Admin or Account Owner key	Yes	Imports users, base roles, teams, schedules, escalation policies, services, and on-call shifts.
Write access: Read-only API Key cleared	Yes	Creates and deletes users, changes base roles, and adds and removes people on teams, schedules, and escalation policies. With a read-only key, every change fails with 403.

Step 3: Collect the values for Trustle

1. Copy the key.

Caution

PagerDuty shows the key once. If you lose it, create a new key.

Trustle field	Where to find it in PagerDuty	Example
API Key	The key from Step 2	<general-access-api-key>
API URL (Optional)	Leave it empty. Trustle uses https://api.pagerduty.com and ignores this field today.	Leave empty

Connect in Trustle

1. In Trustle, go to Connections.
2. Under SaaS Applications, find PagerDuty and click Connect.
3. Enter a Connection Name, for example PagerDuty production. Description is optional.
4. Enter the values from Step 3.
5. Click Test Connection.
6. After the test passes, click Save Connection.

Note

Test Connection fails only when PagerDuty rejects the key. It does not check the role of the key or write access. Do the steps in Verify after the first sync.

Verify

1. On the Connections page, open the PagerDuty connection.
2. Wait for the first sync to finish.
3. Check that the user count and the team count match PagerDuty.

If something is missing, see Troubleshooting.

Caution

• When a base-role grant ends, Trustle sets the user’s base role to Manager. The user does not get their earlier role back.
• PagerDuty does not let Trustle remove a user from a team while the user is on that team’s escalation policy. Trustle then removes the user from the team’s escalation policies and their schedules, and removes the user from the team. Check on-call coverage after such a removal.

Security notes

Note

• Use a dedicated key for Trustle only.
• Store the key in a secret manager. Never commit it to a repository.
• Rotate the key on your normal schedule. Then paste the new key into the Trustle connection.

Troubleshooting

Test Connection fails

PagerDuty rejected the key (401). Check these values:

• API Key: copy the whole key. Check that nobody deleted it in API Access Keys.
• Region: a key from an EU account fails. Contact Trustle support.

Test Connection passes, but users or teams are missing after the sync

Someone without the Admin or Account Owner role created the key. Create a new key as an Admin or Account Owner in Step 1. Then paste it into the Trustle connection.

Every change fails with 403

The key is read-only. Create a new key with Read-only API Key cleared. Then paste it into the Trustle connection.

Trustle cannot create a user

• 402: the PagerDuty account has no free user licenses. Free a license or buy more.
• 409: a PagerDuty user already has this email address.

Trustle cannot give an admin a team role

PagerDuty returns 400 with “admin cannot take team role responder”. A PagerDuty Admin can only have the Manager team role. Request the Manager role on the team for that user.

None of these fixes work

Email support@trustle.com. Include the error message, the connection name, and the PagerDuty subdomain. Never send a secret, key, or token.