Resources have scopes, and applications can request an access token that is associated with specific scopes when the token is granted. The endpoint enforces access through the encoded representation of the scopes in the access token. The endpoint decodes the token to determine the permissions allowed for the application.

Scopes define the permissions for an application or a user. The scopes associated with the actor determine the resources that the actor can access. For example, an actor with a PingOne API resource access token that includes the p1:read:user scope has read access to view their own user resource data.

Custom resource scopes

You can define a custom resource, such as https://api.photos.com that has associated scopes, such as edit:photos, upload:photos, and delete:photos. The POST /environments/{environmentId}/resources/{resourceId}/scopes endpoint defines a new scope associated with the https://api.photos.com custom resource, which is identified by the {{resourceId}} variable in the request URL. The new custom scope grants actors access to otherwise resources on the https://api.photos.com custom resource server.

PingOne resource scopes

The PingOne API is one of two predefined resources in the PingOne platform. The PingOne API resource has several predefined self-management scopes associated with it that grant users access to PingOne resources. The self-management scopes specified in an authorization request, such as p1:update:user or p1:reset:userPassword identify the resources that end user can access to perform self-management actions. For a list of PingOne API self-management scopes, see PingOne self-management scopes.

Resource scopes and access tokens

Scopes from one resource, such as PingOne API (https://api.pingone.com), cannot be included in an access token with scopes from another custom resource such as https://api.photos.com. However, you can include the platform’s predefined OpenID Connect resource (openid) scopes in an access token along with scopes from another resource. For more information about OpenID Connect scopes, see OpenID Connect (OIDC) scopes.

PingOne access control scopes

Most PingOne API scopes cannot be modified. However, user scopes such as the p1:read:user and p1:update:user can be modified to add or remove user schema attributes. In addition, PingOne supports custom PingOne access control scopes that use the syntax p1:read:user:{suffix} and p1:update:user:{suffix} for these two platform scopes. These custom PingOne scopes designate a specific set of user schema attributes, which is often a subset of attributes that the user is allowed to read or update. For example, a p1:update:user:email-only scope could remove all other user schema attributes except the user’s email address. A user with this scope could update only their email address. All other visible attributes would not allow modification. For more information, see Access services through scopes and roles.

Scopes and authorize requests

The following authorization request shows a authorization_code grant type, in which the p1:read:user scope is specified, ensuring that this permission is encoded into the returned access token:

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:user&acr_values=Single_Factor'

You can specify more than one scope (from the same resource or from the openid resource) in the authorization request by adding additional scope names separated by spaces.

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:user p1:update:user:email-only p1:reset:userPassword&acr_values=Single_Factor'

The examples that follow show common actions to find and manage resource scope entities. You need the Client Application Developer role to perform operations on resources entities.

For more information about scopes, see Configure access through scopes and roles.

Resource scopes data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the scope.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the scope resource’s unique identifier.
name A string that specifies the resource name.
resource.id A string that specifies the unique identifier of the resource entity associated with the scope.
schemaAttributes An array that specifies the user schema attributes that can be read or updated for the specified PingOne access control scope. The value is an array of schema attribute paths (such as username, name.given, shirtSize) that the scope controls. This property is supported only for the p1:read:user, p1:update:user and p1:read:user:{suffix} and p1:update:user:{suffix} scopes. No other PingOne platform scopes allow this behavior. Any attributes not listed in the attribute array are excluded from the read or update action. The wildcard path (*) in the array includes all attributes and cannot be used in conjunction with any other user schema attribute paths.
updatedAt The time the resource was last updated.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request could not be completed.
401 You do not have access to this resource.
404 The requested resource was not found.