Advanced Permissions

Permissions allows administrators to manage how users interact with Services, Escalation Policies, and Schedules.

Getting Started with Advanced Permissions

Advanced Permissions allow you to specify the team-wide role that a user has on any given team, and also the level of access a user has to objects (services, escalation policies, and schedules).

Availability of Advanced Permissions

Advanced Permissions are available to customers on our Platform Business and Enterprise plans. Please contact our Sales Team if you would like to upgrade to a plan with this feature.

If you are already on a Platform Business or Enterprise plan but do not yet have advanced permissions enabled, contact PagerDuty Support to request enablement.

Otherwise, if advanced permissions are not available to you, you can still use Basic User Roles to control what level of access your users have in your PagerDuty account.

Best Practices

In following with the principle of least privilege, best practices dictate that you should only grant users as much access as they need to be effective in their role. In practice, this means you’ll typically want to limit the number of users with a Global Admins or Manager role, especially at larger organizations. For responders, a common pattern is to set the lowest access level as the base role, Observer, and grant additional permissions with great access as needed.

Fixed Roles vs. Flexible Roles

There are three fixed roles — Account Owner, Global Admin, and Stakeholder. Every PagerDuty account has one Account Owner, who has full access to everything in the account. Global Admins have mostly the same privileges as the Account Owner, the one difference being that only the Account Owner has access to the Account Settings menu, where billing info, for example, lives. You’ll most likely want to limit the number of Global Admins, since they have so much power.

Flexible roles are where Permissions get “interesting,” since they start with a base role (Observer, Team Responder, Responder, or Manager), and a Global Admin or the Account Owner can assign additional permissions to various objects in the account.

Someone in a managerial role will most likely need to access schedules and escalation policies, and would be granted a Manager base permission. Since Managers can create, update, and delete all objects in the account (except other users), no additional permissions are required.

For someone who is more involved in the day-to-day of responding to incidents, it might make sense to give them an Observer base permission (view all objects, but unable to take any action), and grant them Manager or Responder access, for example, to the objects where they need more agency.

If you’ve already spent some time organizing users into Teams, Team-based Permissions, is a quick way to give a user a specific access level to all objects associated with their Team.

Another solution may be to set a user's base permission to Team Responder. This access level allows responders to take action on incidents belonging to their Teams, and there shouldn’t be an immediate need to set any additional permissions (unless you’d like to restrict or grant agency on objects outside of the user's Team, or to modify objects on their own team, in which case you can grant them the Manager role on the team in question).

Fixed Roles

Users in a Fixed Role have the same level of access to all objects in the account, and they cannot be granted additional permissions or overridden.

Stakeholder
Global Admin
Account Owner

View services, schedules, and escalation policies

Create/delete REST API keys matching permissions level

Configure other users' base roles and additional permissions

Add new users

Delete users

Edit other users’ profiles and password

Add/edit/delete:

  • On-call schedules
  • Scheduling overrides
  • Escalation policies
  • Services
  • Maintenance windows
  • Teams
  • Response plays

Trigger, acknowledge, reassign, and resolve incidents

Enable and edit Single Sign-On (SSO) properties

Change the account owner

Edit billing info

Delete the account

  • Account Owner — Full access to create, update, and delete objects, including a user’s permissions. This access cannot be restricted. Can also access the Billing page.
  • Global Admin — Full access to create, update, and delete objects, including a user’s permissions. This access cannot be restricted.
  • Stakeholder — Can view objects, but cannot make any modifications. Cannot be given Additional Permissions.

Flexible Roles

Flexible Roles give the Account Owner and Global Admins a way to create custom roles, and grant users the level of access they need to specific objects.

Flexible Roles start with selecting one of four Base Permissions, which act as a starting point for a role to build off of.

Restricted Access*
Observer
Responder
Manager

Receive additional permissions

Create/delete user level REST API keys matching permissions level

View services, schedules, and escalation policies

View teams

Trigger, acknowledge, reassign, and resolve incidents

*

Create/delete overrides on schedules

Add/edit/delete:

  • On-call schedules
  • Escalation policies
  • Services
  • Maintenance windows
  • Teams
  • Response plays

Add new users

* Restricted Access users cannot see anything in the account until they're added to a Team, where they are assigned a Team role.

* If an incident is assigned to an Observer, either by another user or by way of an escalation policy, then the Observer will be able to respond to that incident only. This prevents incidents from being in a triggered state and having no users able to respond to it.

In summary:

None of the flexible roles can create new users; this can only be done by users with a base role of Admin or Account owner.

  • Manager — Full access to create, update, and delete objects and all of their configuration.
  • Responder — Can take action on incidents and create overrides.
  • Observer — Can view objects, but cannot make any modifications, except for incidents (if they are assigned to them).
  • Restricted Access — No implied permissions

In addition to the base permissions listed above, the Account Owner or a Global Admin can grant additional permissions to give a user Manager, Responder, or Observer access (as outlined above) to one or more service (and its related incidents), escalation policy, and schedule.

The Team Responder Role

This role (team_responder value for the role user property) in advanced permissions has the same overall effect as it does for basic permissions:

  • The user by default has read-only access to everything in the account, except private teams;
  • The user obtains the responder role for any teams to which they are added, by default.

Once the user is added to a team, their role on the team will be automatically set to "Responder". However, the Team Responder role counts as a flexible role, and any permissions explicitly granted to them will supersede their built-in default.

Permissions in the Web UI

You can access Permissions on the user profile page by clicking the Permissions tab. All users can review their permissions here, and this also where the Account Owner and Global Admins can set users’ permissions.

Setting a User’s Permissions

As an example, let’s say you’d like to give a user, Karen Vick, global Observer access, and Manager access on the Services that touch her job.

  1. Go to Karen’s profile page and click Edit.
  2. Under Select a Base Role, select Observer.
  1. Under Additional Permissions, select the services where you’d like the user to have Manager access.
  1. Click Save.

Karen is now an Observer globally with Manager access on the "Voice" and "Load Balancer" services.

Additionally, users can have different access levels to various objects. The following screenshot shows Manager access on the "Voice" and "Load Balancer" services, and Responder access on the "Operations" schedule:

Rest API Access

Users can create personal REST API keys on their User Settings page of the user profile. Keys created this way will provide access to the REST API that matches their user permissions.

As an example of what this permission-gating looks like, a user with the role of "user" can create an API key that will allow them to edit a schedule, but not add new users to the PagerDuty platform.

What Old Roles do the New Roles Correspond With?

When an account migrates from Basic to Advanced Permissions, most user roles are automatically mapped to the corresponding new role. The Account Owner or Global Admins can make additional adjustments as required.

Basic Permissions
Advanced Permissions

Account Owner

Account Owner

Admin

Global Admin

Stakeholder

Stakeholder

User

Manager

Limited User

Responder

Team Responder

Team Responder

Please note there is not an Observer role on Basic Permissions.

Team-based Permissions

You can give a user access to a Team’s objects by setting them as a Manager, Responder, or Observer on that Team. This grants them the according level of access to their Team’s services, escalation policies, and schedules.

The Account Owner, Global Admins, and Managers on a Team can configure other users’ team roles. Additionally, Team Managers can create new escalation policies, schedules and services for their Team.

The Account Owner, Global Admins, and Stakeholders cannot have their Team access configured. The Account Owner and Global Admins will have manager access to the Team by default, and Stakeholders will be observers.

Team-Level Role

When determining whether a user should have access to an object (a service, escalation policy, or schedule), PagerDuty will first look whether they are a member of the Team to which that object belongs, and then use their Team role. If the object is not part of a Team (or a user is not part of the Team, to which the object belongs), PagerDuty will apply the user’s account-wide role.

External Visibility

The Account Owner, Admins, and Team Managers can control a Team’s external visibility, which will determine whether non-Team members can see associated services, schedules, and escalation policies. If a user is not part of a Team, and that Team’s visibility is set to private, objects associated with that Team will be filtered out of the web UI for that user. The REST API reflects this, too, and will only return objects that a user is allowed to see.

Visibility restrictions will not apply to the Account Owner or Global Admins, who are able to view and administer all objects in the account.

Precedence of Permissions

More specific and granular permissions take precedence over less-specific permissions. The user’s status as a global administrator, and the team visibility settings, take precedence over all other permissions.

Whether a user has a specific level of permission to perform any given task on an object, i.e. create, edit or view a Service, Escalation Policy or Schedule, is determined by performing the following tests. The first applicable condition determines if the user has permission to perform the task:

  1. Is the user a Global Admin or Account Owner?
  2. Does the object belong to a team whose visibility setting is Private, and is the user not a member of it?
  3. Does the user have any specific object-level permissions for the action?
  4. If the object belongs to a team, is the user a member of the team, and what is their role on that team?
  5. What is the user’s default, account-wide role?

Example 1: A user can have the Responder role on a team, but be granted Observer access to a given service on that team whose incidents they should be able to observe, but not acknowledge or resolve, because object-level permissions have higher precedence than team-level permissions.

Example 2: A user’s default role could be observer, but they could be made a manager of a specific team, giving them stakeholder access to all other teams and their respective objects, but the ability to manage their own team.

Permissions on Incidents

In the PagerDuty data model, incidents' team affiliation, which determines the level of permission that users have on them, is that of the service on which they were originally triggered. Moreover, incidents are immutable with respect to the service on which they were created, and so, once triggered, cannot be re-associated with another service.

Note, therefore, that if an incident is delegated an escalation policy on another team, any users on that team who are not also members of the original team with which the incident's service is affiliated will only have as much as their base role in terms of permissions to act upon the incident. This is with the exception of the direct assignees (on the new escalation policy). Only the direct assignees on the escalation policy, if their base role or role on the other team is lower than responder, will get elevated responder privileges on the incident.

Roles in the REST API and SAML

When provisioning a user through the REST API or SAML, the user will by default be given the Manager (a.k.a. User) role, unless specified in the user's role property. The value set for it must be one of a set of fixed values that is recognized by our internal APIs, or our web services will respond with status 400 Invalid Request.

The values of the role field of user records, and also the permissions system, are as follows:

Title
Value
Flexible or Fixed

Global Admin

admin

Fixed

Global Stakeholder

read_only_user

Fixed

Manager / User

user

Flexible

Responder

limited_user

Flexible

Team Responder

team_responder

Flexible

Observer

observer

Flexible

Restricted Access

restricted_access

Flexible

Account Owner *

owner

Fixed

* Cannot be created through API / SAML