Advanced Permissions

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

Getting Started with Advanced Permissions

Permissions allow you great flexibility in determining what objects (services, escalation policies, and schedules) users have access to. This article goes over best practices and offers example use cases.

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, 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, create overrides, and set maintenance windows for objects 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).

Permissions and User Roles for Standard and Enterprise Plans

Advanced Permissions are available to customers on our current Standard and Enterprise plans. Please contact our Sales Team if you would like to upgrade to a plan featuring custom Permissions.

Advanced Permissions allow administrators to manage how users interact with Services, Escalation Policies, and Schedules. This article covers the basic permissions of each user role, and how to set object-specific permissions. For advanced permissions using team roles, refer to Team-Based Permissions.

If Advanced Permissions haven’t been enabled on your PagerDuty account, please reference this article for more information about basic user roles.

Permissions Overview

Under the Permissions schema, a user can either have a Fixed Role, or a Flexible Role with base permissions and additional permissions.

Fixed Roles

User’s 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

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/Team Responder**
Manager

Receive additional permissions

Create/delete 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

* Restricted Access users cannot see anything in the account until they're added to a Team, where they are assigned a Team role. This role addresses multi-tenancy use cases, for example.
**Team Responders can only take action on objects associated with their Team(s).

  • Manager — Full access to create, update, and delete objects and all of their configuration.
  • Responder — Can take action on incidents, create overrides, and set maintenance windows.
  • Team Responder — For objects belonging to their teams, able to take action on incidents, create overrides, and set maintenance windows.
  • Observer — Can view objects, but cannot make any modifications.

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.

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.

Precedence of Permissions

If the user does not have a fixed role, i.e. global admin (in which case they would have permissions to everything) or a stakeholder (in which case they cannot have any object-specific permissions), the object-specific permissions take precedence over their default role.

For a full overview of how permissions are evaluated, including when team roles are involved, see Team-based Permissions.

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?

If you’re used to user roles prior to Permissions, the table below shows what roles will be called going forward. When Permissions launches, user roles will automatically be mapped from the old one to the new one with its corresponding Base Permissions. The Account Owner or Global Admins can add Additional Permissions as required.

Prior role name
Role name under Permissions

Account Owner

Account Owner

Admin

Global Admin

Stakeholder

Stakeholder

User

Manager

Limited User

Responder

Team Responder

Team Responder

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.

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, 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.

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

Observer

observer

Flexible

Restricted Access

restricted_access

Flexible

Account Owner *

owner

Fixed

* Cannot be created through API / SAML

Advanced Permissions

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