PagerDuty API Authentication: Methods and Security (2026)

Authentication overview

The PagerDuty API utilizes API tokens as the primary mechanism for authenticating requests. These tokens grant programmatic access to your PagerDuty account, allowing applications and scripts to interact with incident data, schedules, users, and other resources. Proper management and secure handling of these tokens are essential to prevent unauthorized access and maintain the integrity of your incident management workflows.

Authentication tokens are passed in the Authorization header of HTTP requests. The PagerDuty API supports different types of tokens, each designed for specific use cases and access levels, ensuring granular control over permissions. For detailed information on specific API endpoints and their requirements, consult the official PagerDuty API reference documentation.

Supported authentication methods

PagerDuty API primarily supports API tokens for authentication. These tokens are unique identifiers that authenticate a user or an integration to the PagerDuty platform. There are two main types of API tokens:

• User API Keys: These keys are tied to a specific PagerDuty user and inherit that user's permissions within the PagerDuty account. They are suitable for scripts or applications that need to perform actions on behalf of a user, such as fetching user-specific schedules or acknowledging incidents as a particular user.
• Integration API Keys: These keys are associated with a specific PagerDuty integration (e.g., a custom service integration). They are typically used for incoming events or for integrations that need to create incidents or trigger alerts without being tied to a specific user's permissions. Integration API keys often have more limited scopes, focusing on specific actions related to the integration they serve.

The choice between a User API Key and an Integration API Key depends on the specific requirements of your application and the principle of least privilege. Always use the token type that grants only the necessary permissions for the task at hand.

Authentication method comparison

Getting your credentials

To interact with the PagerDuty API, you will need to generate an API token. The process varies slightly depending on whether you need a User API Key or an Integration API Key.

Generating a User API Key

1. Log in to your PagerDuty account.
2. Navigate to Integrations > API Access Keys.
3. Click the +Create New API Key button.
4. Provide a descriptive Description for your key (e.g., "My Application Integration").
5. (Optional) Select a Read-only checkbox if the key should only be able to retrieve data.
6. Click Create Key.
7. The API key will be displayed. Copy it immediately, as it will not be shown again for security reasons.

For a step-by-step guide, refer to the PagerDuty API Access Keys documentation.

Generating an Integration API Key

Integration API keys are typically generated when setting up a new service integration within PagerDuty. The exact steps depend on the type of integration (e.g., Events API V2 integration, a custom service integration).

1. Log in to your PagerDuty account.
2. Navigate to Services > Service Directory.
3. Select an existing service or create a new one.
4. Go to the Integrations tab for that service.
5. Click +Add an integration.
6. Choose an integration type (e.g., "Events API V2" for generic event submission).
7. Provide a Name for the integration and click Add Integration.
8. The Integration Key (also known as the Routing Key for Events API V2) will be displayed. Copy it for use in your application.

More details on setting up service integrations can be found in the PagerDuty Events API V2 documentation.

Authenticated request example

Once you have obtained an API token, you can use it to make authenticated requests to the PagerDuty API. The token must be included in the Authorization header of your HTTP request, prefixed with Token token=.

Example using cURL (User API Key)

This example demonstrates fetching a list of users from your PagerDuty account using a User API Key.

curl -X GET \
  -H "Accept: application/vnd.pagerduty+json;version=2" \
  -H "Authorization: Token token=YOUR_USER_API_KEY" \
  "https://api.pagerduty.com/users"

Example using cURL (Events API V2 Integration Key)

This example demonstrates sending an event to PagerDuty using an Events API V2 Integration Key (Routing Key). Note that for Events API V2, the key is sent in the request body as routing_key, not in the Authorization header.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{ "routing_key": "YOUR_INTEGRATION_KEY", "event_action": "trigger", "payload": { "summary": "High CPU utilization on web server", "source": "monitoring-tool", "severity": "critical" } }' \
  "https://events.pagerduty.com/v2/enqueue"

Using PagerDuty SDKs

PagerDuty provides official SDKs for several programming languages, simplifying the process of making authenticated requests. These SDKs handle the underlying HTTP requests and authentication headers. For instance, in Python, you might configure the API client with your token:

from pagerduty.api import PagerDutyAPI

api = PagerDutyAPI(api_key="YOUR_USER_API_KEY")
users = api.users.list()
for user in users:
    print(user.name)

Refer to the PagerDuty documentation on using API keys with client libraries for language-specific examples.

Security best practices

Securing your PagerDuty API tokens is critical to protect your incident management system from unauthorized access and potential disruption. Adhere to the following best practices:

• Principle of Least Privilege: Always generate API tokens with the minimum necessary permissions required for the task. For example, use a read-only key if your application only needs to fetch data.
• Environment Variables: Avoid hardcoding API keys directly into your source code. Instead, store them as environment variables or use a secure configuration management system. This prevents accidental exposure in version control and makes it easier to manage keys across different environments. The Google Cloud security best practices recommend using secret management services.
• Regular Rotation: Regularly rotate your API keys, especially for long-lived integrations or if there's any suspicion of compromise. PagerDuty allows you to revoke existing keys and generate new ones.
• Secure Storage: Store API keys securely. For local development, use a .env file that is excluded from version control. In production, consider dedicated secret management services like AWS Secrets Manager, Google Secret Manager, or HashiCorp Vault.
• Access Control: Limit who has access to generate, view, and manage API keys within your PagerDuty account. Leverage PagerDuty's role-based access control (RBAC) features to enforce this.
• Audit Logs: Regularly review PagerDuty's audit logs to monitor API key usage and detect any unusual or unauthorized activity.
• Revoke Compromised Keys: Immediately revoke any API key that you suspect has been compromised.
• HTTPS Only: Always ensure that your applications communicate with the PagerDuty API over HTTPS to encrypt data in transit and prevent man-in-the-middle attacks. This is standard for modern APIs, as detailed by the Mozilla Developer Network on secure contexts.
• Token Scopes: While PagerDuty API keys don't have explicit OAuth-style scopes, the distinction between User API Keys and Integration API Keys serves a similar purpose, providing a level of functional scope. Understand these differences to apply the correct key type.