PagerDuty User Management API Guide

Auth method: API Token (Bearer) - both account-level tokens and user-level tokens supported. OAuth 2.0 is also supported for third-party app integrations.

Setup steps

1. Log in to PagerDuty as an Admin or Account Owner.
2. Navigate to Integrations > API Access Keys.
3. Click 'Create New API Key', provide a description, and choose Read-only or Full Access.
4. Copy the generated token - it is shown only once.
5. Include the token in all requests as the Authorization header: 'Authorization: Token token='.
6. For OAuth 2.0: register an app under Developer Mode, obtain client_id/client_secret, and follow the authorization code flow to obtain a Bearer token.

Required scopes

List Users

• Method: GET
• URL: https://api.pagerduty.com/users
• Watch out for: Use the 'query' param to filter by name/email. 'include[]' param can expand contact_methods, notification_rules, teams. Max limit=100.

Request example

GET /users?limit=25&offset=0&query=john
Authorization: Token token=YOUR_TOKEN
Accept: application/vnd.pagerduty+json;version=2

Response example

{
  "users": [{"id":"P1A2B3C","name":"John Doe","email":"john@example.com","role":"user"}],
  "offset": 0,
  "limit": 25,
  "more": false,
  "total": 1
}

Get User

• Method: GET
• URL: https://api.pagerduty.com/users/{id}
• Watch out for: Use include[] to sideload related objects; without it, contact_methods and notification_rules arrays are empty.

Request example

GET /users/P1A2B3C?include[]=contact_methods
Authorization: Token token=YOUR_TOKEN
Accept: application/vnd.pagerduty+json;version=2

Response example

{
  "user": {
    "id": "P1A2B3C",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user",
    "time_zone": "America/New_York"
  }
}

Create User

• Method: POST
• URL: https://api.pagerduty.com/users
• Watch out for: The 'from' header (From: admin@example.com) is required for audit trail purposes on some account configurations. An invitation email is automatically sent to the new user.

Request example

POST /users
Authorization: Token token=YOUR_TOKEN
Content-Type: application/json

{"user":{"type":"user","name":"Jane Smith","email":"jane@example.com","role":"user","time_zone":"UTC"}}

Response example

{
  "user": {
    "id": "P9X8Y7Z",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "user",
    "invitation_sent": true
  }
}

Update User

• Method: PUT
• URL: https://api.pagerduty.com/users/{id}
• Watch out for: PUT replaces the full user object. Always include 'type':'user' in the body. Changing role to 'owner' is not allowed via API.

Request example

PUT /users/P9X8Y7Z
Authorization: Token token=YOUR_TOKEN
Content-Type: application/json

{"user":{"type":"user","name":"Jane Smith","role":"admin"}}

Response example

{
  "user": {
    "id": "P9X8Y7Z",
    "name": "Jane Smith",
    "role": "admin"
  }
}

Delete User

• Method: DELETE
• URL: https://api.pagerduty.com/users/{id}
• Watch out for: Users cannot be deleted if they are the only member of an on-call schedule or escalation policy. Remove them from all schedules/policies first. Deletion is permanent.

Request example

DELETE /users/P9X8Y7Z
Authorization: Token token=YOUR_TOKEN
Accept: application/vnd.pagerduty+json;version=2

Response example

HTTP 204 No Content

List User Contact Methods

• Method: GET
• URL: https://api.pagerduty.com/users/{id}/contact_methods
• Watch out for: Contact method types: email_contact_method, phone_contact_method, sms_contact_method, push_notification_contact_method. Phone/SMS require E.164 format.

Request example

GET /users/P1A2B3C/contact_methods
Authorization: Token token=YOUR_TOKEN
Accept: application/vnd.pagerduty+json;version=2

Response example

{
  "contact_methods": [
    {"id":"CM1","type":"email_contact_method","address":"john@example.com","label":"Default"}
  ]
}

Create User Contact Method

• Method: POST
• URL: https://api.pagerduty.com/users/{id}/contact_methods
• Watch out for: Phone and SMS contact methods require country_code as an integer. Push notification contact methods cannot be created via API - they are registered by the mobile app.

Request example

POST /users/P1A2B3C/contact_methods
Content-Type: application/json

{"contact_method":{"type":"sms_contact_method","country_code":1,"address":"5551234567","label":"Mobile"}}

Response example

{
  "contact_method": {
    "id": "CM2",
    "type": "sms_contact_method",
    "address": "5551234567",
    "label": "Mobile"
  }
}

Get Current User

• Method: GET
• URL: https://api.pagerduty.com/users/me
• Watch out for: Only works with user-level API tokens, not account-level tokens. Returns 404 with account-level tokens.

Request example

GET /users/me
Authorization: Token token=USER_LEVEL_TOKEN
Accept: application/vnd.pagerduty+json;version=2

Response example

{
  "user": {
    "id": "P1A2B3C",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "admin"
  }
}

• Rate limits: PagerDuty enforces rate limits per API token. Standard limit is 960 requests per minute. Limits are communicated via response headers.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: When rate limited, the API returns HTTP 429. The Retry-After header indicates seconds to wait. Headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are included in responses.
• Pagination method: offset
• Default page size: 25
• Max page size: 100
• Pagination pointer: offset and limit; response includes 'more' boolean and 'total' count

• Webhooks available: Yes
• Webhook notes: PagerDuty Webhooks v3 (current) deliver HTTP POST payloads to configured endpoints for account events. User-specific events are limited; most webhook events are incident/service-focused.
• Alternative event strategy: For comprehensive user lifecycle events, use SCIM provisioning with an IdP (Okta, Entra ID, OneLogin) which provides real-time sync. Alternatively, poll GET /users on a schedule.
• Webhook events: user.created, user.updated, user.deleted

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Business or Enterprise

• Endpoint: https://app.pagerduty.com/scim/v2

• Supported operations: GET /Users - list users, GET /Users/{id} - get user, POST /Users - create user, PUT /Users/{id} - replace user, PATCH /Users/{id} - update user (including deactivate via active=false), DELETE /Users/{id} - delete user, GET /Groups - list teams, POST /Groups - create team, PATCH /Groups/{id} - update team membership, DELETE /Groups/{id} - delete team

Limitations:

• Requires SSO (SAML) to be configured before SCIM can be enabled.
• Business plan or higher required; not available on Free or Professional plans.
• SCIM token is separate from REST API tokens - generated in SSO settings.
• User role assignment via SCIM is limited; advanced role mapping may require REST API.
• Push notification contact methods cannot be managed via SCIM.
• SCIM Groups map to PagerDuty Teams, not escalation policies or schedules.

Three scenarios cover the majority of programmatic user lifecycle needs. First, provisioning a new user with an SMS contact method requires three sequential calls: POST /users (capture the returned id), POST /users/{id}/contact_methods (SMS requires country_code as an integer and E.

164-compatible number without the '+' prefix), then POST /users/{id}/notification_rules referencing the contact method id. The 'From' header (acting admin email) is required on POST /users for audit trail compliance on many account configurations - omitting it can produce a 400.

Second, deprovisioning requires dependency resolution before deletion: GET /users/{id}? include[]=teams, then DELETE /teams/{team_id}/users/{user_id} for each team, followed by a schedule and escalation policy audit via GET /schedules and GET /escalation_policies.

DELETE /users/{id} returns 400 if the user is the sole member of any on-call schedule layer or escalation policy step - automate this dependency check or deletions will fail silently in batch jobs.

Third, SCIM sync with Okta uses base URL https://app.pagerduty.com/scim/v2 with a SCIM-specific Bearer token generated under SSO settings - entirely separate from REST API tokens and not visible on the API Access Keys page.

Provision a new user with SMS contact method and notification rule

1. POST /users with name, email, role, time_zone, and type='user' to create the user. Note the returned user id.
2. POST /users/{id}/contact_methods with type='sms_contact_method', country_code, address (phone number), and label.
3. Note the returned contact_method id.
4. POST /users/{id}/notification_rules with start_delay_in_minutes, contact_method reference (id + type), and urgency ('high' or 'low').

Watch out for: Include the 'From' header on POST /users. SMS contact methods require E.164-compatible number without '+' prefix - pass country_code separately as integer.

Deprovision a user (offboarding)

1. GET /users/{id}?include[]=teams to identify team memberships.
2. For each team, DELETE /teams/{team_id}/users/{user_id} to remove team membership.
3. GET /schedules and GET /escalation_policies to check if user is referenced; remove or replace them.
4. DELETE /users/{id} once the user has no blocking schedule/policy dependencies.

Watch out for: DELETE /users/{id} returns 400 if the user is the only member of any on-call schedule layer or escalation policy step. Automate dependency checks before deletion.

Sync users via SCIM with Okta

1. Confirm account is on Business or Enterprise plan.
2. Enable SSO/SAML in PagerDuty under Account Settings > Single Sign-On.
3. Navigate to Account Settings > SCIM and generate a SCIM API token.
4. In Okta, add the PagerDuty app from the Okta Integration Network.
5. Configure SCIM provisioning in Okta using base URL 'https://app.pagerduty.com/scim/v2' and the SCIM token as Bearer auth.
6. Enable Okta features: Push New Users, Push Profile Updates, Push Groups (maps to PagerDuty Teams).
7. Assign users/groups in Okta to trigger provisioning.

Watch out for: SCIM token is distinct from REST API tokens. SSO must be fully configured and tested before enabling SCIM. Deactivating a user in Okta sets active=false in PagerDuty (suspends) but does not delete them.

The most common integration failure is conflating SCIM and REST API credential types: SCIM tokens are generated under Account Settings > Single Sign-On, not the API Access Keys page, and the two are not interchangeable.

PUT /users/{id} replaces the full user object - partial updates that omit fields will null them out, so always include 'type':'user' in the body. The 'owner' role cannot be set via API and must be changed in the web UI, which breaks fully automated provisioning flows that need to transfer account ownership.

The identity graph implication is also significant: SCIM Groups map to PagerDuty Teams, not to escalation policies or schedules, so team membership sync via SCIM does not guarantee on-call coverage is correctly assigned - that layer requires separate REST API calls and cannot be inferred from IdP group membership alone.