Access services through scopes and roles

Self-service platform API resources and scopes

The self-management resources described in the following section are applicable to users only. They are granted on authorization_code and implicit authorization flows. You cannot grant PingOne self-management scopes for an application in which the grantTypes property specifies the client_credentials grant type. For more information, see Administrator permissions and role assignments.

PingOne self-management scopes

The self-management scopes specified in an authorization request identify the resources that end user can access to perform self-management actions. These scopes use the following naming format to represent a self-management permission:


For example, the self-management scope to read user information is p1:read:user.

The PingOne platform includes the following self-management scopes:

Scope Description
p1:read:user Users can retrieve their own user identity and all attributes.
p1:update:user Users can modify the attributes of their own user identity.
p1:update:userMfaEnabled Users can enable and disable multi-factor authentication for their own user identity.
p1:create:device Users can create multi-factor authentication devices for their own user identity.
p1:read:device Users can retrieve multi-factor authentication devices for their own user identity.
p1:update:device Users can update multi-factor authentication devices for their own user identity.
p1:delete:device Users can delete multi-factor authentication devices for their own user identity.
p1:read:userPassword Users can retrieve the password state for their own user identity.
p1:reset:userPassword Users can reset the password for their own user identity.
p1:validate:userPassword Users can validate the password for their own user identity.
p1:read:userLinkedAccounts Users can read linked accounts for their own user identity.
p1:delete:userLinkedAccounts Users can read delete linked accounts for their own user identity.
p1:create:pairingKey Users can create a pairing key for their own user identity.
p1:delete:pairingKey Users can delete a pairing key for their own user identity.
p1:read:pairingKey Users can read a pairing key for their own user identity.

User scopes enable self-service actions

User scopes provide privileges to specific actions, giving end users the ability to interact with their own profile data. An example of a commonly used user scope is p1:reset:userPassword. This scope, when included in an authorization request, generates access tokens that give users permission to run the self-service password reset action.

The following sample shows an authorization_code request that includes the reset password scope.

curl --request GET \
  --url '{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri='

For more information about authorization requests, see OpenID Connect/OAuth 2.

OpenID Connect (OIDC) scopes

Standard OpenID Connect scopes control which user claims are included in an id_token or in a userinfo response. Unlike other resources, scopes from this resource can be included in an access token along with scopes from another resource.

PingOne supports the following OIDC scopes:

Scope Description
profile This scope value requests access to the end-user’s default profile claims, which are: name, family_name, given_name, middle_name, preferred_username, picture, zoneinfo, locale, and updated_at.
email This scope value requests access to the email claim.
address This scope value request access to the address claim.
phone This scope value requests access to the phone_number claim.

OIDC scopes for user information

The following sample shows an implicit authorization request with an id_token response type. The scope parameter specifies the required openid scope. It also specifies the optional profile scope to provide access to the end-user’s default profile claims.

curl -X GET \
  '{environmentId}/as/authorize?client_id={clientId}&redirect_uri= profile'

For more information about retrieving scopes for a specified resource, see Get scopes for a resource.

Custom resource scopes

The PingOne platform includes two predefined resources,, which is a defined resource that represents the PingOne APIs, and openid, which represents OpenID Connect scopes.

In addition, PingOne lets you define custom resources and their associated scopes. Custom resources can be associated with an application either exclusively, or in addition to the platform’s predefined resources. When an application is associated with both the PingOne resource and a custom resource, an authorization request cannot include scopes from both PingOne and the custom resource.

If you do specify scopes from two different resources in the authorize request, the request returns the following error:

The request could not be completed. One or more validation errors were in the request.: May not request scopes for multiple resources (Correlation ID: 8E7B23B8-6761-4532-8AFC-4B723D52FF5D).

If more than one resource is associated with the application, actors need to make separate authorization requests to get a token for the desired resource scopes.

Administrator permissions and role assignments

Unlike user self-service applications, administrator applications use role assignments to determine the actions a user or client can perform. For external API client applications, the access tokens do not use scopes to control access to resources. Instead, the actor’s role assignments determine resource access.

Worker application permissions

Administrator applications that interact with non-self Platform APIs are classified as a WORKER application type. This application type supports only the OPENID_CONNECT protocol. A worker application that uses the client_credentials grant type inherits the same role assignments as the user or application that created the application. These role assignments can be cross-environment, which allows access to APIs for other environments.

Role assignments determine access to APIs (see Application role assignments and User role assignments). Users and clients cannot create or use clients that have more privileges than the worker application itself. For example, an actor with the Identity Data Admin role cannot create a worker application that has Environment Admin privileges. Likewise, access to an application’s client secret is restricted based on the accessing user’s or application’s role assignments. If a client has the Environment Admin role, an Identity Admin is not able to see the client secret.

PingOne roles include a set of permissions that allow access to PingOne resources. For example, the Identity Data Admin role grants access to PingOne resources for these user management actions:

  • Read, create, update, and delete user resources
  • Read, create, update, and delete device management resources
  • Assign identity resources
  • Bulk user import
  • Read, create, update and delete population resources
  • Update user password resources
  • Read user password state resources
  • Read password policy resources
  • Read audit reporting activities resources
  • Read schema resources

The actor (user or client) assigning roles to the application must have the permissions that they are trying to assign. In other words, the requesting user or client must have the same (or broader) role assignments as the target application’s role assignments. This prevents a lesser privileged user (such as a Client Application Developer) from creating a more privileged client_credentials application (such as an Environment Admin).

When retrieving access tokens for WORKER applications, the authorization service checks to make sure the user or client has at least one role assignment. If not, the token request is rejected. If at least one role assignment exists, the authorization service creates a token with no scopes except for the requested OIDC scopes. When accessing platform APIs with this token, it retrieves the actor’s entitlements, which ensures that clients and users can access only the resources that their role assignments allow.

Worker applications and environments

When a worker application with Environment Admin privileges creates a new environment, that application is given Identity Data Admin and Client Application developer role assignments for the new environment. Only the worker application can perform Identity Data Admin operations in that environment (see the list of Identity Data Admin actions above). However, the worker application can give the same role assignment to another user or worker application. For more information about roles and role assignments, see Roles, Application role assignments, and User role assignments.