Connect PagerDuty

Agent markdown

Before you start

Engine operator registers one PagerDuty OAuth app using Classic User OAuth for the Init platform. Connection admin/user authorizes that app for their PagerDuty account during Connect.

You need:

• A PagerDuty account with permission to register apps (Integrations → App Registration, labels may vary by plan).
• A PagerDuty user who can authorize OAuth apps for the customer account (and the correct service region, US or EU).
• The engine public base URL for the redirect URL.

Configure the provider

One-time platform PagerDuty app (Engine operator)

1. In PagerDuty, open app registration and create a new app with OAuth 2.0 functionality.

2. Choose Classic User OAuth (Init’s pack uses Classic User OAuth with PKCE, not Scoped OAuth).

3. Set the Redirect URL to:

   {FUSE_PUBLIC_URL}/v1/oauth/pagerduty/callback

4. Configure permission scopes to the minimum Classic scopes your Init actions require (read and/or write). Do not request write access unless write actions are enabled.

5. Register the app and store the Client ID and Client Secret in the Fuse environment as PAGERDUTY_OAUTH_CLIENT_ID and PAGERDUTY_OAUTH_CLIENT_SECRET. Never commit these values.

Per-account authorization (Connection admin/user)

Customers authorize the platform app through Init Connect. They do not paste API keys into Connect for this provider.

Connect to Init

1. Connection admin/user starts a PagerDuty Connect session.
2. Sign in to PagerDuty (correct US/EU identity host for the account) and approve the requested scopes.
3. Init completes the authorization-code + PKCE callback and stores the connection. No customer credential fields are submitted.

If Init later enables write actions that require the Classic write scope, reconnect so PagerDuty re-consents.

Permissions

Classic User OAuth scopes for this pack are read and write (with write implying read). The generated action matrix lists which actions need which Classic scope.

Baseline identity scope (runtime policy, not action-declared): Init always includes openid so it can validate the PagerDuty ID token and bind the account. This is separate from action-required read/write scopes.

Authorization acts on behalf of the consenting PagerDuty user. Use an account with only the operational privileges you intend Init to exercise.

Verify the connection

1. Confirm Connect completes and Init shows an active PagerDuty connection for the expected account/subdomain.
2. Run a safe read such as listing services or on-calls the user can view.
3. Success looks like PagerDuty API reads succeeding without 401/403 and the connection remaining bound to the authorized account.

Rotate or revoke access

• Rotate platform secrets (Engine operator): rotate the OAuth client secret in PagerDuty app settings, update PAGERDUTY_OAUTH_CLIENT_SECRET, then retire the old secret.
• Revoke customer access (Connection admin/user): remove the authorized app from the PagerDuty account, or delete the Init connection.
• After Classic scope expansion (for example adding write), reconnect/reauthorize before write actions succeed.

Troubleshooting