PagerDuty

The PagerDuty auth provider enables tools and agents to call PagerDuty APIs  on behalf of a user using OAuth 2.0 authentication.

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, which provides pre-built tools for interacting with PagerDuty
• Your app code that needs to call the PagerDuty API
• Or, your custom tools that need to call the PagerDuty API

Configuring PagerDuty auth

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, register an app in your PagerDuty account. App Registration requires a base role of Manager, Global Admin, or Account Owner.

Arcade doesn’t use the separate Events Integration functionality, so you can skip it.

Scoped OAuth apps are confidential clients: PagerDuty requires the client secret and PKCE on every authorization. Arcade’s included PagerDuty provider sends both.

A Scoped OAuth app works right away on the PagerDuty account that registered it. To authorize users on other PagerDuty accounts, PagerDuty must publish the app, and an administrator on each of those accounts must install it.

For details, refer to PagerDuty’s Register an App  and OAuth Functionality  guides.

Next, add the PagerDuty app to Arcade.

Configuring your own PagerDuty Auth Provider in Arcade

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

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

auth:
  providers:
    - id: default-pagerduty
      description: The default PagerDuty provider
      enabled: true
      type: oauth2
      provider_id: pagerduty
      client_id: ${env:PAGERDUTY_CLIENT_ID}
      client_secret: ${env:PAGERDUTY_CLIENT_SECRET}

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 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 to understand how this works.

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

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=["users.read"],
)
 
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...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade();
 
const userId = "{arcade_user_id}";
 
// Start the authorization process
let authResponse = await client.auth.start(userId, "pagerduty", {
  scopes: ["users.read"],
});
 
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...

Using PagerDuty auth in custom tools

You can use the pre-built Arcade PagerDuty MCP Server 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 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:

from typing import Annotated
 
import httpx
from arcade_mcp_server import Context, tool
from arcade_mcp_server.auth import PagerDuty
 
 
@tool(
    requires_auth=PagerDuty(
        scopes=["users.read"],
    )
)
async def get_current_user(
    context: Context,
) -> Annotated[dict, "The current user information."]:
    """
    Retrieve information about the authenticated user from PagerDuty.
    """
    url = "https://api.pagerduty.com/users/me"
    headers = {
        "Authorization": f"Bearer {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

The Arcade PagerDuty MCP server requests these PagerDuty scopes:

• escalation_policies.read
• incidents.read
• incidents.write
• oncalls.read
• schedules.read
• services.read
• teams.read
• users.read
• users:contact_methods.read

The PagerDuty API reference  lists the scope each endpoint requires. For more details, refer to PagerDuty’s Private Apps  guide.

Troubleshooting

• Arcade asks the user to authorize again after every sign-in: PagerDuty doesn’t reject a scope the app isn’t registered for. It issues a token with only the openid scope instead, so Arcade keeps prompting. Check that the app uses Scoped OAuth, not Classic User OAuth, and that it’s registered with every scope listed under Permissions.