# Provisioning for PagerDuty

### Overview

The Veza integration for PagerDuty enables user provisioning, team membership management, and user deletion capabilities. This integration allows you to synchronize identity information, manage team assignments, and automate the user lifecycle from onboarding to offboarding.

| Action Type            | Description                                                                                                      | Supported |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | --------- |
| `SYNC_IDENTITIES`      | Synchronizes identity attributes between systems, with options to create new identities and update existing ones | ✅         |
| `MANAGE_RELATIONSHIPS` | Controls team memberships for PagerDuty users                                                                    | ✅         |
| `DELETE_IDENTITY`      | Permanently removes users from PagerDuty                                                                         | ✅         |

This document includes steps to enable the PagerDuty integration for provisioning, along with supported actions and notes. See [Supported Actions](#supported-actions) for more details.

### Enabling provisioning

#### Prerequisites

1. You will need administrative access in Veza to configure the integration.
2. Ensure you have an existing [PagerDuty integration](/4yItIzMvkpAvMVFAamTf/integrations/integrations/pagerduty.md) in Veza or add a new one for use with provisioning.
3. Verify your PagerDuty integration has completed at least one successful extraction.
4. The PagerDuty integration will need the following configuration:
   * **API Access Token**: A PagerDuty API token with full read and write permissions (not read-only)
   * **API URL**: Your PagerDuty instance URL (e.g., `https://yourcompany.pagerduty.com` or use `api.pagerduty.com` for API-direct access)
   * **Admin Email**: The email address of a PagerDuty admin user (required for user creation and modification operations)

{% hint style="info" %}
For testing and development, you can create a free PagerDuty developer account at <https://developer.pagerduty.com/sign-up/>. Developer accounts are limited to a maximum of 3 simultaneous users, but you can delete and recreate users as needed.
{% endhint %}

#### Configuration Steps

To enable the integration:

1. In Veza, go to the **Integrations** overview
2. Search for or create a PagerDuty integration
3. Ensure the following configuration is complete:
   * **URL**: Your PagerDuty domain URL (e.g., `https://yourcompany.pagerduty.com`)
   * **Token**: A valid API access key with write permissions
   * **Admin Email**: The email address used for administrative operations
4. Check the box to **Enable usage for Provisioning**

To verify the health of the provisioning data source:

1. Open **Lifecycle Management** > **Integrations** (in the Products section of the navigation sidebar), or the main **Integrations** page (in the Featured section)
2. Search for the integration and click the name to view details
3. In the **Properties** panel, click the magnifying glass icon under **Lifecycle Management Enabled**

### Supported Actions

{% hint style="warning" %}
PagerDuty does not support account deactivation or suspension. Users can only be fully deleted from the system. The `DEPROVISION_IDENTITY` action is not available for this integration. Use `DELETE_IDENTITY` instead when removing user access.
{% endhint %}

PagerDuty can also be a *target* for identity management actions, based on changes in another external source of truth or as part of a workflow.

The integration supports the following [Actions](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/policies-workflows/actions.md):

#### Sync Identities

Primary action for user management (creating or updating users):

* **Entity Types:** `OAA.PagerDuty.User`
* **Create Allowed:** Yes - New user identities can be created if not found

The following attributes can be synchronized:

<details>

<summary>PagerDuty User Attributes</summary>

| Property      | Required | Type   | Description                                                         | Notes                                          |
| ------------- | -------- | ------ | ------------------------------------------------------------------- | ---------------------------------------------- |
| `email`       | Yes      | String | Email address of the user (used as unique identifier)               | Must be unique across all PagerDuty users      |
| `name`        | Yes      | String | Full name of the user                                               |                                                |
| `role`        | No       | String | PagerDuty role assigned to the user                                 | Common values: `user`, `admin`, `limited_user` |
| `job_title`   | No       | String | Job title of the user                                               |                                                |
| `time_zone`   | No       | String | Time zone for the user in tzinfo format (e.g., 'America/New\_York') | Must be a valid IANA time zone string          |
| `description` | No       | String | Description or notes about the user                                 |                                                |

</details>

{% hint style="info" %}
**Identity Model**: PagerDuty users are uniquely identified by their email address. The `email` attribute is used for all user lookup and synchronization operations.
{% endhint %}

#### Manage Relationships

Controls team memberships for PagerDuty users:

* **Supported Relationship Types:**
  * **PagerDutyTeam:** Team membership
* **Assignee Types:** PagerDuty User
* **Supports Removing Relationships:** Yes

Teams are referenced by their PagerDuty team ID (e.g., `PCALT99`). Team IDs can be found in the PagerDuty UI under **People** > **Teams** or via the Veza graph. In Veza, team entity IDs follow the format: `custom_provider:application:[datasource_id]:pagerduty:team:[team_id]`.

#### Delete Identity

Permanently removes a user from PagerDuty:

* **Entity Type:** `OAA.PagerDuty.User`
* **Remove All Relationships:** Yes - All team memberships are automatically removed
* **Deletion Method:** Permanent deletion via PagerDuty API
* **Requirements:** The user must exist in PagerDuty (identified by email or user ID)

{% hint style="danger" %}
**Permanent Action**: User deletion in PagerDuty is permanent and cannot be undone. All user data, including incident history and on-call schedules, will be affected. PagerDuty does not support user suspension or deactivation - deletion is the only method to remove user access.
{% endhint %}

### Example Workflows

#### Example: Onboarding New Users to PagerDuty

To provision a new user in PagerDuty and assign them to relevant teams:

1. Create a policy with your HRIS or identity source (e.g., Workday, Okta)
2. Configure a workflow for **user creation** with condition: `{job_role} == "Engineer"`
3. Add a **Sync Identities** action:
   * Target Integration: PagerDuty
   * Entity Type: `OAA.PagerDuty.User`
   * Create if Not Found: Enabled
   * Attribute mapping:

     ```txt
     email: {work_email}
     name: {first_name} {last_name}
     role: user
     time_zone: {time_zone | DEFAULT_VALUE: "America/New_York"}
     job_title: {job_title}
     ```

#### Example: Offboarding Users from PagerDuty

To remove a departing user from PagerDuty:

1. Create a policy with your HRIS or identity source
2. Configure a workflow for **user termination** with condition: `{employee_status} == "Terminated"`
3. Add a **Delete Identity** action:
   * Target Integration: PagerDuty
   * Entity Type: `OAA.PagerDuty.User`
   * Identifier mapping: `email: {work_email}`

{% hint style="warning" %}
Before deleting a user, ensure they are not assigned to any active on-call schedules or escalation policies that could impact incident response.
{% endhint %}

### Additional Notes

#### API Rate Limiting

PagerDuty enforces API rate limits on all operations. The Veza integration automatically handles rate limiting by:

* Monitoring the `X-RateLimit-Remaining` and `X-RateLimit-RetryAfter` response headers
* Automatically retrying requests after the rate limit reset time
* Using exponential backoff for failed requests

If you encounter errors during high-volume operations, consider:

* Scheduling bulk provisioning operations during off-peak hours
* Batching user creation across multiple workflow executions
* Contacting PagerDuty support to discuss rate limit increases for your account

#### PagerDuty User Limits

Free and developer PagerDuty accounts have user limits:

* **Developer accounts**: Maximum of 3 simultaneous users
* **Free tier**: Check your PagerDuty plan for specific limits

For production use with PagerDuty, verify that your PagerDuty subscription supports the number of users you plan to manage.

#### Team Entity IDs

When working with PagerDuty teams:

* Teams are referenced by their PagerDuty team ID (e.g., `PCALT99`)
* Team IDs can be found in the PagerDuty UI under **People** > **Teams** or via the Veza entity browser
* In Veza, team entity IDs follow the format: `custom_provider:application:[datasource_id]:pagerduty:team:[team_id]`


---

# 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://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/pagerduty/provisioning.md?ask=<question>
```

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.