--- title: Resource Scopes description: 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. component: pingone-api page_id: pingone-api:platform:resources/resource-scopes canonical_url: https://developer.pingidentity.com/pingone-api/platform/resources/resource-scopes.html section_ids: custom-resource-scopes: Custom resource scopes pingone-resource-scopes: PingOne resource scopes resource-scopes-and-access-tokens: Resource scopes and access tokens pingone-access-control-scopes: PingOne access control scopes scopes-and-authorize-requests: Scopes and authorize requests adding-mapped-claims-to-an-id-token-or-userinfo: Adding mapped claims to an ID token or userinfo resource-scopes-data-model: Resource scopes data model resource-scopes-events-generated: Resource scopes events generated response-codes: Response codes --- # Resource Scopes 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 {{apiPath}}/v1/environments/{{envID}}/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, refer to [PingOne self-management scopes](../../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html). ## Resource scopes and access tokens Scopes from the `PingOne API` resource (`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 PingOne. For more information about OpenID Connect scopes, refer to [OpenID Connect (OIDC) scopes](../../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html). With custom resource scopes, the default application configuration allows scopes from one custom resource, with or without the platform's predefined OpenID Connect resource (`openid`) scopes in an access token. However, if the appplication configuration sets the `requestScopesForMultipleResourcesEnabled` OIDC property to `true`, then the application accepts scopes from multiple custom resources. For example if `Resource1` defines `scopeR1-a` and `Resource2` defines `scopeR2-a`, then an authorize request for an app with `requestScopesForMultipleResourcesEnabled` enabled supports a `scope` parameter of: `--data-urlencode 'scope=openid scopeR1-a scopeR2-a'`. For use cases in which an application requests scopes from multiple custom resources, the following settings and attribute mappings must be consistent among custom resources for PingOne to complete the request: * The access token's time to live value must be the same across the requested custom resources. Otherwise, the request returns an error. * The mapping configuration of the `sub` attribute must be the same across the requested custom resources. Otherwise, the request returns an error. * Attributes defined in the requested custom resources can share the same attribute name (overlapping attributes), use unique attribute names (non-overlapping attributes), or contain a mixture of overlapping and non-overlapping attributes. * For overlapping attributes, mapping configurations must be the same. Otherwise, the request returns an error. * For non-overlapping attributes, mapping configurations can be the same or different. * The attributes in the resulting access tokens are a union of all the attributes defined in the requested custom resources. * Scope names must be unique across all custom resources that can be requested at the same time by admin-enabled applications. * If an environment includes PingOne Authorize, when defining a custom resource, if the admin chooses to include user permissions in access tokens, the admin must ensure that permission names are unique across all custom resources that can be requested at the same time by admin-enabled applications. ## 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, refer to [Access services through scopes and roles](../../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html). ## 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: ```sh curl --request GET \ --url 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&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. ```sh curl --request GET \ --url 'https://auth.pingone.com/{{envID}}/as/authorize?response_type=code&client_id={{appID}}&redirect_uri={{redirect_uri}}&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, refer to [Configure access through scopes and roles](../../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html). ## Adding mapped claims to an ID token or userinfo If the resource's `type` property is `OPENID_CONNECT`, you can add scopes to the resource that include custom mapped claims. The `mappedClaims` property in the `POST {{apiPath}}/v1/environments/{{envID}}/resources/{{openidResourceID}}/scopes` request specifies the IDs of the resource attributes to add to the scope. For example, the OpenID Connect `profile` scope includes the following predefined profile claims: `name`, `given_name`, `family_name`, `middle_name`, `nickname`, `preferred_username`, `picture`, `zoneinfo`, `locale`, `updated_at`, `profile`, `website`, `gender`, and `birthdate`. If you add the ID for a predefined claim that already exists in the scope, such as `given_name`, it is ignored in the response. However, if you add the predefined `phone_number` attribute to the `profile` scope, the ID for the `phone_number` attribute is returned in the `mappedClaims` property in the response. ```json "mappedClaims": [ "579dc6f8-bf83-43ae-816c-324506b5de21" ], ``` You can add custom claims to an OpenID Connect scope that you define using the [Create Resource Attribute](resource-attributes.html#post-create-resource-attribute) endpoint. The create request can include the `idToken` and `userInfo` properties to designate (globally) whether the claim should be added to the ID token and returned by the userinfo endpoint. You can specify that the `idToken` and\`userInfo\` properties are both `true`, one can be `true` and the other `false`, but both properties cannot be set to `false`. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [Application Attribute Mapping](../applications/application-attribute-mapping.html) service's data model also supports the `idToken` and `userInfo` properties to specify (and override the global setting at the application level) whether the claim should be added to the ID token or returned by the userinfo endpoint. | []() ## Resource scopes data model | Property | Type | Required? | Mutable? | Description | | ------------------ | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createdAt` | Date | N/A | Read-only | The time the resource was created. | | `description` | String | Optional | Mutable | The description of the scope. | | `environment.id` | String | Required | Immutable | The environment resource's unique identifier associated with the resource. | | `id` | String | Required | Immutable | The scope resource's unique identifier. | | `mappedClaims` | String\[] | Optional | Mutable | A list of custom resource attribute IDs. This property applies only for the resource with its `type` property set to `OPENID_CONNECT`. Moreover, this property does not display predefined OpenID Connect (OIDC) mappings, such as the `email` claim in the OIDC `email` scope or the `name` claim in the `profile` scope. You can create custom attributes, and these custom attributes can be added to `mappedClaims` and will display in the response. | | `name` | String | Required | Mutable | The resource scope name. Scope names are only unique for the resource and not the environment. | | `resource.id` | String | Required | Immutable | The unique identifier of the resource entity associated with the scope. | | `schemaAttributes` | String\[] | Optional | Mutable | 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` | Date | N/A | Read-only | The time the resource was last updated. | ## Resource scopes events generated Refer to [Audit Reporting Events](../audit-activities.html#audit-reporting-events) for the events generated. ## 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. | > **Collapse: Related topics** > > * [Access tokens and ID tokens](../../foundations/authentication-concepts/access-tokens-and-id-tokens.html) > > * [Access services through scopes and roles](../../foundations/pingone-roles-scopes-and-permissions/access-services-through-scopes-and-roles.html) > > * [Add a custom claim to an access token](../../workflow-library/introduction.html#add-a-custom-claim-to-an-access-token)