The PagerDuty REST API provides  200+ endpoints for users to programmatically access objects and workflows in the PagerDuty platform. Teams leverage these APIs to streamline creating and managing users, teams, services and other components for their environment. 

Up until now, access to the REST API has been authorized and authenticated via API Keys. These keys are managed in the web UI, and provide an all-or-nothing access to the objects in the account, making them too permissive for many teams, so PagerDuty Engineering has been working on creating a comprehensive set of API scopes for use with OAuth2.0 Tokens. 

Each object in the PagerDuty REST API will have at least one scope, read, and many objects will also have write. You’ll be able to tune your apps to have only the access they are required to have to work correctly, without worrying that they’ll also have access to everything else in your account.

For folks currently using API keys, they’ll continue to work for the time being (stay tuned for potential EOL in the future), but migrating to Scoped OAuth will help teams manage access and adhere to principles of least privilege.

For a video introduction to API Scopes, check out this video on our YouTube channel.

Set up an App

The first change you’ll notice when setting up API access with scopes is that the access is managed via an app. These won’t be managed via the “API Access Keys” section under the “Integrations” menu; you’ll want to head to “App Registration” (formerly known as “Developer Mode”) instead, and proceed through the app configuration process. Setting these up is limited to the administrators and owners of your account. 

When the app is created, you’ll have the option to add Scoped OAuth to it:

For apps that support Scoped OAuth, the next dialog will allow you to select which objects should be available to Tokens derived from this app access. You’ll be able to select as many or as few as are appropriate for your use case:

After clicking Save, you’ll be presented with a popover window containing two important pieces of information: the Client ID and Client Secret that will be used to provision tokens for this app access.

You’ll need these to provision tokens, so store them in a vault or other location or app you use for certificates, passwords, or secrets.

Finding Scopes

As you can see from the above screen capture, there are a lot of potential scopes your tokens might need, depending on which objects will be accessed via the API. 

Fortunately, the API documentation has been updated to include the necessary scopes for all of the object endpoints. Each type of request will have a note that includes the scope and whether the request will require read or write access. Broadly, though, requests using GET methods – used for listing or getting information – will only require read access, while PUT, POST, and DELETE requests will require write access.

Requesting Tokens

Tokens, associated with the Scoped Client within your app, will be requested from https://identity.pagerduty.com/oauth/token using the credentials you received when the app was created. You’ll find the request format in the API docs here. The other required data are your region (US or EU) and subdomain (youraccount.pagerduty.com). Each token you request must specify which scopes it will be valid for.

curl -i --request POST \

  https://identity.pagerduty.com/oauth/token \

  --header "Content-Type: application/x-www-form-urlencoded" \

  --data-urlencode "grant_type=client_credentials" \

  --data-urlencode "client_id={CLIENT_ID}" \

  --data-urlencode "client_secret={CLIENT_SECRET}" \

  --data-urlencode "scope=as_account-us.companysubdomain incidents.read services.read"

The scopes included in a token can be the full set of scopes included in the app, or a subset of those scopes, depending on how your organization prefers to manage the tokens. The tokens are returned in a JSON document:

{

  "access_token": "pdus+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "scope": "as_account-us.companysubdomain incidents.read services.read",

  "token_type": "bearer",

  "expires_in": 2592000

}

These tokens have an expiration! This is a big change from the never-expiring API keys. Tokens will have to be rotated every 24 hours. 

Additionally, to help folks with repository scanners ensure that tokens are not checked in, each PagerDuty token will start with “pd<region>+”, so either pdus+ or pdeu+ so that tokens are easily identified.

Once a token is created, how it is distributed and managed is up to you. The tokens are not listed in the web UI or otherwise available on the platform. From within the app page you’ll have the ability to revoke all the tokens associated with the app, but not individual ones.

Using Tokens

If you’ve been accessing the API via custom scripts, you’ll need to do some updates to use the new tokens.  

For shell scripts that use command line tools like curl or wget to make their https requests, you’ll need to update the Authorization header:

--header "Authorization: Bearer $TOKEN" 

Similarly, in tools like Postman, you’ll want to set Authorization to a Bearer token. For more on how to do this in Postman, see the Postman documentation.

If you are using any of the various client libraries for PagerDuty’s API, check the documentation for those projects to determine if a code change is required. For example, in pdpyras, a session constructor is available specifically for OAuth2.0 tokens:

# REST API v2 with an OAuth2 access token:

session_oauth = pdpyras.APISession(OAUTH_TOKEN, auth_type='oauth2')

Depending on the programming languages you are using, there may be more sophisticated solutions or support for OAuth2.0 tokens available. Sample code for several languages is also included in the documentation on the developer site.

Managing tokens and apps

How you design your app and token granularity is up to you and the security requirements of your organization. There are a few suggested methods to help you get started. 

Who Provisions Tokens

Because the Scoped OAuth tokens will have a 30-day expiration, organizations with a lot of teams programmatically accessing the PagerDuty API will likely find it easier to share the Client ID and Client Secret with individual teams and allow them to provision their own tokens. Administrators may choose to create apps for each team or type of application to control who will have access to the API and which objects.

Smaller teams, or those who need more control over access to resources, may want to retain the Client ID and Client Secret to the account administrators, who will then create and share tokens out to teams via secure storage.

Fully Scoped Apps, Limited Scope Tokens

For use cases that will require access to a lot of different objects, you can provision the app to include all scopes. Since tokens can be requested with a subset of all allowed scopes, individual tokens can be constrained to just what the client application will use in the API.

This method can cut down on the number of apps that need to be managed in the PagerDuty account. Administrators can provision apps for teams or departments, and provide tokens with more limited scopes.

Try it out and let us know

Scoped OAuth is available now as an Early Access feature, and will be generally available on all accounts at the end of May 2023. Try it out and let us know what you think! Sign up for early access at https://www.pagerduty.com/early-access/ or contact your account team to learn more. You can also join our community forum if you have questions.