# Connect PagerDuty

Canonical URL: https://docs.fuse.init.inc/integrations/pagerduty/setup

Register a Classic User OAuth app and create a verified Init connection.



## Before you start [#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 [#configure-the-provider]

### One-time platform PagerDuty app (**Engine operator**) [#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**) [#per-account-authorization-connection-adminuser]

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

## Connect to Init [#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 [#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 [#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-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 [#troubleshooting]

| Symptom                                 | What to check                                                                               |
| --------------------------------------- | ------------------------------------------------------------------------------------------- |
| Redirect URL error                      | Must match `{FUSE_PUBLIC_URL}/v1/oauth/pagerduty/callback`.                                 |
| Wrong OAuth mode                        | Platform app must use Classic User OAuth; Scoped OAuth is not this Init pack.               |
| Region confusion                        | Authorize with the PagerDuty identity for the account’s US or EU region.                    |
| Write actions fail after product change | Reconnect to obtain Classic `write` (Init collapses `read`+`write` requests appropriately). |
| Fuse cannot start OAuth                 | Confirm `PAGERDUTY_OAUTH_CLIENT_ID` and `PAGERDUTY_OAUTH_CLIENT_SECRET`.                    |