--- title: PingOne self-management scopes description: 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. component: pingone-api page_id: pingone-api:foundations:pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles/pingone-self-management-scopes canonical_url: https://developer.pingidentity.com/pingone-api/foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles/pingone-self-management-scopes.html section_ids: user-scopes-enable-self-service-actions: User scopes enable self-service actions access-control-self-scopes: Access control self scopes restricted-access-scopes: Restricted access scopes license-capabilities-and-access-scopes: License capabilities and access scopes authoritative-identity-providers-and-access-scopes: Authoritative identity providers and access scopes --- # PingOne self-management scopes 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::` 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. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. ```bash 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, refer to [OpenID Connect/OAuth 2](../../../auth/openid-connect-oauth-2.html) in the *PingOne Platform APIs*. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For information about adding custom claims to an access token, refer to [Resource attributes](../../../platform/resources/resource-attributes.html) in the *PingOne Platform APIs*. | ## 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, refer to [Resource scopes](../../../platform/resources/resource-scopes.html). 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 {{apiPath}}/v1/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. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | | | | - | --------------------------------------------------------------------------------------- | | | 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`