# Pagerduty
Connecting PagerDuty gives SureCloud read access to your PagerDuty account's services, escalation policies, on-call schedules, incidents, and users. SureCloud monitors incident response configuration to verify that all critical services have an escalation policy assigned, checks that on-call schedules have continuous coverage with no gaps, audits user and team access to confirm that service ownership is appropriate, and collects incident records to provide evidence that alerts are being acknowledged and resolved within defined timeframes. This provides continuous evidence that your incident response programme is operationally ready and that on-call coverage is maintained.
{% hint style="info" %}
SureCloud connects to PagerDuty using OAuth 2.0 where available, or a REST API key scoped to a dedicated service account for accounts that prefer key-based authentication. Both methods are supported.
{% endhint %}
## Authentication and setup
{% tabs %}
{% tab title="OAuth 2.0 (recommended)" %}
{% stepper %}
{% step %}
#### Register an OAuth application in PagerDuty
In the [PagerDuty Developer Portal](https://developer.pagerduty.com/), navigate to **My Apps → Create New App**.
* **App name**: `SureCloud CCM`
* **Brief description**: SureCloud Continuous Control Monitoring
* **Category**: Monitoring
Under **Functionality → OAuth 2.0**, click **Add Functionality** and set:
* **Redirect URLs**: enter the SureCloud OAuth callback URL provided in **SureCloud → Integrations → PagerDuty → Connect**
* **Permission scope**: `read` (read-only access to all account resources)
Click **Save App** and note the **Client ID** and **Client Secret**.
{% endstep %}
{% step %}
#### Complete the OAuth flow in SureCloud
In SureCloud, navigate to **Integrations → PagerDuty → Connect** and provide:
* **Client ID**
* **Client Secret**
Click **Connect via OAuth**. SureCloud redirects to PagerDuty for authorisation. An account with the **Global Admin** or **Account Owner** role must approve the authorisation to grant access across all services and teams.
SureCloud maintains access via automatic refresh token rotation.
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="REST API Key" %}
{% stepper %}
{% step %}
#### Generate a REST API key
In PagerDuty, navigate to **Integrations → API Access Keys → Create New API Key**.
* **Description**: `SureCloud CCM`
* **API key type**: **Read-only API key**
Click **Create Key** and copy the token value immediately.
{% hint style="warning" %}
PagerDuty REST API keys do not expire automatically. Rotate this key every 90 days as a security best practice. Update the rotated value in **SureCloud → Integrations → PagerDuty → Edit Connection**.
{% endhint %}
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → PagerDuty → Connect (API Key)** and provide:
* **REST API key**
Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
## Endpoints
| API Call | Use Case |
| --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET /services` | Enumerate all services with their escalation policy assignment and integration count |
| `GET /escalation_policies` | Read escalation policy configuration; detect services with no escalation policy |
| `GET /schedules` | Enumerate on-call schedules and their coverage layers |
| `GET /schedules/{id}/users` | Read the users currently on call for each schedule |
| `GET /oncalls` | Read current and upcoming on-call assignments; detect schedule gaps |
| `GET /incidents` | Retrieve incidents within the collection window with status, urgency, and acknowledgement time |
| `GET /incidents/{id}/log_entries` | Read the full event log for an incident including acknowledgement and resolution timestamps |
| `GET /users` | Enumerate all users with their role and contact method configuration |
| `GET /teams` | List all teams and their member composition |
| `GET /abilities` | Verify account capabilities and feature availability |
## Pagination
The PagerDuty REST API uses offset-based pagination via `offset` and `limit` query parameters. The response `more` boolean field indicates whether additional pages exist. SureCloud increments `offset` by `limit` (up to 100 per page) while `more` is `true`.
```json
{
"services": [
{
"id": "P1ABC23",
"name": "Payment API",
"status": "active",
"escalation_policy": { "id": "P9XYZ01", "summary": "Payment team escalation" }
}
],
"limit": 100,
"offset": 0,
"more": true,
"total": 847
}
```
## Required permissions
For OAuth 2.0, the authorising account must hold the **Global Admin** or **Account Owner** role to grant the `read` scope across all services, teams, and schedule data. Team-scoped accounts can only read data within their assigned teams.
For REST API key, the **Read-only API key** type provides access to all read endpoints without any write capability. No specific user role is required for the key itself — the key grants read access to all account resources.
{% hint style="info" %}
PagerDuty **Teams** features (team-scoped access) are available on Business and Digital Operations plans. On lower plans, all users can read all services and schedules. On higher plans with team-scoped access enabled, SureCloud requires a Global Admin account or key to ensure full visibility across all teams.
{% endhint %}
## Polling frequency
| Data type | Collection interval |
| ------------------------------------------- | ------------------- |
| Service and escalation policy configuration | 24 hours |
| On-call schedule coverage | 6 hours |
| Current on-call assignments | 6 hours |
| Incidents and resolution times | 1 hour |
| User and team inventory | 24 hours |
## Troubleshooting
Some services are not appearing in SureCloud
On PagerDuty accounts with team-scoped access enabled, services assigned only to specific teams may not be visible to the API key or OAuth account if it lacks Global Admin access.
Confirm the API key is a **Read-only** key generated at the account level (not scoped to a team), or that the OAuth authorising account holds the **Global Admin** role. Navigate to **PagerDuty → User → Profile** to verify the account role.
On-call schedule gaps are not being detected
SureCloud evaluates schedule gaps by reading the `oncalls` endpoint for current and near-future on-call assignments. A gap is identified when a schedule layer has no assigned user for a time period.
Confirm schedules are configured with at least one layer in **PagerDuty → Schedules → \[Name] → Edit Schedule**. Schedules with no layers defined will always appear as a gap.
Incident acknowledgement and resolution times are missing
Acknowledgement and resolution timestamps are sourced from the incident log entries endpoint (`/incidents/{id}/log_entries`). SureCloud collects log entries for incidents within the polling window. For very high-volume accounts with thousands of incidents per hour, log entry collection may be throttled by the PagerDuty rate limit (960 requests per minute for REST API keys).
If acknowledgement data is consistently missing for recent incidents, contact SureCloud support to adjust the incident log entry collection strategy for high-volume accounts.
OAuth authorisation is failing with "Insufficient scope"
The PagerDuty OAuth app must be registered with the `read` permission scope. If the app was registered without a scope or with a narrower scope, SureCloud will receive 403 errors on some endpoints.
In the [PagerDuty Developer Portal](https://developer.pagerduty.com/), navigate to **My Apps → \[SureCloud CCM] → OAuth 2.0** and confirm the **Permission scope** is set to `read`. If the scope needs updating, re-authorise the connection after saving the change.
PagerDuty REST API reference PagerDuty authentication guide
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/pagerduty.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.