import { Tabs, Callout, Steps } from "nextra/components";

# PagerDuty

The PagerDuty auth provider enables tools and agents to call [PagerDuty APIs](https://developer.pagerduty.com/api-reference/) on behalf of a user using OAuth 2.0 authentication.

<Callout type="warning">
Arcade currently supports **Classic** PagerDuty OAuth apps only. Choose Classic and select either **read-only** or **read/write** access. Newer Web App or other models are not supported. See [PagerDuty OAuth functionality](https://developer.pagerduty.com/docs/oauth-functionality).
</Callout>

<Callout>
  Want to quickly get started with PagerDuty in your agent or AI app? The
  pre-built [Arcade PagerDuty MCP
  Server](/resources/integrations/development/pagerduty-api) is what you want!
</Callout>

### What's documented here

This page describes how to use and configure PagerDuty auth with Arcade.

This auth provider is used by:

- The [Arcade PagerDuty MCP Server](/resources/integrations/development/pagerduty-api), which provides pre-built tools for interacting with PagerDuty
- Your [app code](#using-pagerduty-auth-in-app-code) that needs to call the PagerDuty API
- Or, your [custom tools](#using-pagerduty-auth-in-custom-tools) that need to call the PagerDuty API

## Configuring PagerDuty auth

<Callout type="info">
  When using your own app credentials, make sure you configure your project to
  use a [custom user
  verifier](/guides/user-facing-agents/secure-auth-production#build-a-custom-user-verifier).
  Without this, your end-users will not be able to use your app or agent in
  production.
</Callout>

In a production environment, you will most likely want to use your own PagerDuty app credentials. This way, your users will see your application's name requesting permission.

Before showing how to configure your PagerDuty app credentials, let's go through the steps to create a PagerDuty app.

### Create a PagerDuty app

To integrate with PagerDuty's API using OAuth 2.0, you'll need to register an app in your PagerDuty account:

<Steps>

#### Access PagerDuty App Registration

1. Log in to your PagerDuty account
2. Navigate to **Integrations** → **App Registration**
3. This is where you'll create and manage your OAuth applications

#### Create a new app

1. Click on **New App** or **Register New App**
2. Fill in the required details:
   - **Application Name**: Choose a descriptive name for your application
   - **Description**: Provide a brief description of your app's purpose
   - **Functionality**: Select both **OAuth 2.0** and **Events Integration** (if needed)

#### Configure OAuth settings

1. Choose **Classic** OAuth and select the permission level:
   - **Read-only** (recommended; all current MCP tools only read data)
   - Or **Read/Write** if you plan custom tools that modify data
2. Add the **Redirect URL** generated by Arcade (see configuration section below) to your app's redirect URLs

#### Save your credentials

1. After creating your app, you'll receive your **Client ID** and **Client Secret**
2. **Important**: Copy and save these credentials immediately, as the Client Secret won't be accessible again

</Steps>

For detailed instructions, refer to PagerDuty's [OAuth 2.0 guide](https://www.pagerduty.com/blog/insights/build-sophisticated-apps-for-your-pagerduty-environment-using-oauth-2-0-and-api-scopes/) and [OAuth documentation](https://developer.pagerduty.com/docs/oauth-functionality).

Next, add the PagerDuty app to Arcade.

## Configuring your own PagerDuty Auth Provider in Arcade

<Tabs items={["Dashboard GUI", "Configuration File"]}>
<Tabs.Tab>

### Configure PagerDuty Auth Using the Arcade Dashboard GUI

<Steps>

#### Access the Arcade Dashboard

To access the Arcade Cloud dashboard, go to [api.arcade.dev/dashboard](https://api.arcade.dev/dashboard). If you are self-hosting, by default the dashboard will be available at http://localhost:9099/dashboard. Adjust the host and port number to match your environment.

#### Navigate to the OAuth Providers page

- Under the **Connections** section of the Arcade Dashboard left-side menu, click **Connected Apps**.
- Click **Add OAuth Provider** in the top right corner.
- Select the **OAuth 2.0** tab at the top.

#### Enter the provider details

- Choose a unique **ID** for your provider (e.g. "arcade-pagerduty").
- Optionally enter a **Description**.
- Enter the **Client ID** and **Client Secret** from your PagerDuty app.
- Configure the OAuth 2.0 endpoints:
  - **Authorization URL**: `https://app.pagerduty.com/oauth/authorize`
  - **Token URL**: `https://app.pagerduty.com/oauth/token`
- Note the **Redirect URL** generated by Arcade. This must be set as one of your PagerDuty app's Redirect URLs.

#### Create the provider

Hit the **Create** button and the provider will be ready to be used.

</Steps>

</Tabs.Tab>

<Tabs.Tab>

### Configure PagerDuty Auth Using Configuration File

<Callout type="info">
  This method is only available when you are [self-hosting the
  engine](/guides/deployment-hosting/on-prem
</Callout>

<Steps>

#### Set environment variables

Set the following environment variables:

```bash
export PAGERDUTY_CLIENT_ID="<your client ID>"
export PAGERDUTY_CLIENT_SECRET="<your client secret>"
```

Or, you can set these values in a `.env` file:

```bash
PAGERDUTY_CLIENT_ID="<your client ID>"
PAGERDUTY_CLIENT_SECRET="<your client secret>"
```

#### Edit the Engine configuration

Edit the `engine.yaml` file and add a new item to the `auth.providers` section:

```yaml
auth:
  providers:
    - id: pagerduty
      description: PagerDuty OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:PAGERDUTY_CLIENT_ID}
      client_secret: ${env:PAGERDUTY_CLIENT_SECRET}
      oauth2:
        scope_delimiter: " "
        authorize_request:
          endpoint: "https://app.pagerduty.com/oauth/authorize"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            scope: "{{scopes}}"
            state: "{{state}}"
        token_request:
          endpoint: "https://app.pagerduty.com/oauth/token"
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json
```

</Steps>

</Tabs.Tab>
</Tabs>

When you use tools that require PagerDuty auth using your Arcade account credentials, Arcade will automatically use this PagerDuty OAuth provider. If you have multiple PagerDuty providers, see [using multiple auth providers of the same type](/references/auth-providers#using-multiple-providers-of-the-same-type) for more information.

## Using PagerDuty auth in app code

Use the PagerDuty auth provider in your own agents and AI apps to get a user token for the PagerDuty API. See [authorizing agents with Arcade](/get-started/about-arcade) to understand how this works.

Use `client.auth.start()` to get a user token for the PagerDuty API:

<Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
<Tabs.Tab>

```python {8-12}
from arcadepy import Arcade

client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable

user_id = "{arcade_user_id}"

# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="pagerduty",
    scopes=[]
)

if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)

# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)

token = auth_response.context.token
# Do something interesting with the token...
```

</Tabs.Tab>

<Tabs.Tab>

```javascript {8-11}
import { Arcade } from "@arcadeai/arcadejs";

const client = new Arcade();

const userId = "{arcade_user_id}";

// Start the authorization process
const authResponse = await client.auth.start(userId, "pagerduty", []);

if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}

// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);

const token = authResponse.context.token;
// Do something interesting with the token...
```

</Tabs.Tab>

</Tabs>

## Using PagerDuty auth in custom tools

You can use the pre-built [Arcade PagerDuty MCP Server](/resources/integrations/development/pagerduty-api) to quickly build agents and AI apps that interact with PagerDuty.

If the pre-built tools in the PagerDuty MCP Server don't meet your needs, you can author your own [custom tools](/guides/create-tools/tool-basics/build-mcp-server) that interact with the PagerDuty API.

Use the `PagerDuty()` auth class to specify that a tool requires authorization with PagerDuty. The `context.authorization.token` field will be automatically populated with the user's PagerDuty token:

```python {8-12,22}
from typing import Annotated

import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import PagerDuty


@tool(
    requires_auth=PagerDuty()
)
async def get_current_user(
    context: ToolContext,
) -> Annotated[dict, "The current user information."]:
    """
    Retrieve information about the authenticated user from PagerDuty.
    """
    url = "https://api.pagerduty.com/users/me"
    headers = {
        "Authorization": context.authorization.token,
        "Accept": "application/vnd.pagerduty+json;version=2",
    }

    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return dict(response.json())
```

## Permissions

PagerDuty Classic apps use two permission levels:

- **read** — Read-only access to PagerDuty resources (recommended; all current MCP tools are read-only)
- **write** — Full read/write access (only needed if you add custom write tools)

For more details about PagerDuty’s OAuth permissions, refer to the [PagerDuty OAuth functionality docs](https://developer.pagerduty.com/docs/oauth-functionality#scopes).