Self-management scopes are applicable to users only. They are granted on authorization_code and implicit authorization flows. PingOne self-management scopes cannot be granted on a client_credentials flow.

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

p1:<permission-action>:<permission-classifier>

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. If the user authenticates with an authoritative identity provider (`user.identityProvider.id` is not `null`), their password state will not be returned with a self-service `GET READ One User` request.
`p1:update:user`	Users can modify the attributes of their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`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 read the password state for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`p1:reset:userPassword`	Users can reset the password for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`p1:validate:userPassword`	Users can validate the password for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`p1:read:userLinkedAccounts`	Users can read linked accounts for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`p1:delete:userLinkedAccounts`	Users can delete linked accounts for their own user identity. This scope is not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).
`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.
`p1:read:sessions`	Users can read sessions for their own user identity.
`p1:delete:sessions`	Users can delete sessions for their own user identity.
`p1:read:userConsent`	Users can read consents for their own user identity.
`p1:verify:user`	Users can verify their own user identity.
`p1:read:oauthConsent`	Users can read oauth scope consents for their own user identity.
`p1:update:oauthConsent`	Users can update oauth scope consents for their own user identity.

Note: The requested user resource or user’s sub-resources must be the same as the user identified by the sub claim (the userId) in the access token. The requested resource must be in the same environment as the environment identified by the env claim in the access token.

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 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&scope=p1:reset:userPassword'

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

For information about adding custom claims to an access token, see Resource attributes.

Access control self scopes

Some PingOne platform self-management scopes allow organizations to specify which user profile attributes are accessible to end users. An administrator might want to prevent end users with access to their profiles from seeing or modifying particular attributes that should remain private, such as custom attributes for entitlements, internal foreign keys, account status information, or any profile data that should not be exposed to an individual user. With access control scopes, organizations can store additional private data in the user profile without risk that the end user can see the data.

The following scopes allow access control:

Scope Description

p1:read:user and p1:read:user:{{suffix}} Users can read any of the user schema attributes defined in the scope’s schemaAttributes property for their own user identity. The p1:read:user scope can be modified using PUT to change the list of user schema attributes. The p1:read:user:{{suffix}} scope is created using POST and must specify at least one user schema attribute in the schemaAttributes property.

p1:update:user and p1:update:user:{{suffix}} Users can modify any of the user schema attributes defined in the scope’s schemaAttributes property for their own user identity. The p1:update:user scope can be modified using PUT to change the list of user schema attributes. The p1:update:user:{{suffix}} scope is created using POST and must specify at least one user schema attribute in the schemaAttributes property. These scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null).

Scope	Description
`p1:read:user` and `p1:read:user:{{suffix}}`	Users can read any of the user schema attributes defined in the scope’s `schemaAttributes` property for their own user identity. The `p1:read:user` scope can be modified using `PUT` to change the list of user schema attributes. The `p1:read:user:{{suffix}}` scope is created using `POST` and must specify at least one user schema attribute in the `schemaAttributes` property.
`p1:update:user` and `p1:update:user:{{suffix}}`	Users can modify any of the user schema attributes defined in the scope’s `schemaAttributes` property for their own user identity. The `p1:update:user` scope can be modified using `PUT` to change the list of user schema attributes. The `p1:update:user:{{suffix}}` scope is created using `POST` and must specify at least one user schema attribute in the `schemaAttributes` property. These scopes are not granted if the user authenticates with an authoritative identityProvider (`user.identityProvider.id` is not `null`).

For example, an access control scope based off of p1:update:user (such as p1:update:user:name that specifies only the ['name.family', 'name.given'] user attribute in the scope’s schemaAttributes property) allows self updates of the first and last name attributes only. For more information about self-scope properties, see Resource scopes.

When the actor is self, the following behaviors apply to the p1:read:user and p1:read:user:{{suffix}} access control scopes for a GET /environments/{{envID}}/users/{{userID}} request:

Attributes that are not included in any provided read scope are excluded from output, except for the id attribute, which is always included in the response if any other user schema attributes are returned.
An attribute that is included in a read scope and present in the user record is included in the response body.
An attribute that is not included in a read scope and present in the user record is excluded from the response body.

If no attributes are included in the provided read scopes (if self has no access), then an HTTP Status 403 error is returned.

Likewise, the following behaviors apply to the p1:update:user and p1:update:user:{{suffix}} access control scopes for a PUT /environments/{{envID}}/users/{{userID}} request:

Attributes that are not included in any provided updates scope are not accessible to end users for update.
Immutable attributes such as id even if included, are not updated. Attempts to update immutable user attributes are ignored.
An attribute that is included in an update scope and present in the user record is accessible to update, unless it is immutable.
An attribute that is not included in an update scope and present in the user record is not accessible to update.
Multi-value attribute updates replace the entire attribute. It is not possible to merge data into an existing set of values.
The multiValued property of an attribute can only be changed from false or null to true, never from true to false.

These scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null).

If the user does not have update access to an attribute, a 403 Forbidden error is returned if an update is attempted for that attribute.

Note: The behaviors listed above for access control scopes also apply to the platform self scopes. In other words, the p1:read:user and p1:update:user self scopes are evaluated by the same rules as p1:read:user:{{suffix}} and p1:update:user:{{suffix}}.

Restricted access scopes

License capabilities and access scopes

License capabilities control access to some PingOne self-service scopes. Your PingOne license can disable access to specific scopes (and their associated permissions) based on the capabilities enabled by the license package. For example, if your PingOne license supports only MFA capabilities, then other self-service capabilities such as canUsePasswordManagement, canUseIdentityProviders, and canUsersUpdateSelf are set to false in the license. With these capabilities set to false, access to the scopes controlled by these capabilities are restricted.

The following capabilities control access to these associated scopes:

Capability	Associated scopes
`canUsePasswordManagement`	`p1:reset:userPassword`, `p1:read:userPassword`
`canUseIdentityProviders`	`p1:read:userLinkedAccounts`, `p1:delete:userLinkedAccounts`
`canUsersUpdateSelf`	`p1:update:user`

If the controlling capability is set to false, authorization requests that specify restricted scopes will not grant a token that includes the restricted scopes. However, if the authorization request also specifies a non-restricted platform scope, such as p1:read:user, the request returns a token that includes only the p1:read:user scope.

Note: The non-restricted scope must be a PingOne platform scope; it cannot be a custom scope.

Authoritative identity providers and access scopes

The following self-service scopes are not granted if the user authenticates with an authoritative identityProvider (user.identityProvider.id is not null).

p1:update:user
p1:update:user:{{suffix}}
p1:read:userPassword
p1:reset:userPassword
p1:validate:userPassword
p1:read:userLinkedAccounts
p1:delete:userLinkedAccounts