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.

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.

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

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:

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:

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.

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.

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