Work with scopes


Scopes

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 application with an access token that includes the p1:read:env:user scope has read access to users resources. A user resource with an access token that includes the p1:read:self:user scope has read access to it own user resource data.

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

curl -k -X POST -H "Accept: application/json" -d 'grant_type=client_credentials&scope=p1:read:env:user' -d 'client_id=my-client-id' -d 'client_secret=76c173fd-f323-2136-b4e6-9d8353d3721b' https://auth.pingone.com/as/token

You can specify more than one scope attribute in the authorization request by adding additional scope names separated by spaces.

curl -k -X POST -H "Accept: application/json" -d 'grant_type=client_credentials&scope=p1:read:env:user p1:create:env:user p1:read:env:userPasswordState' -d 'client_id=my-client-id' -d 'client_secret=76c173fd-f323-2136-b4e6-9d8353d3721b' https://auth.pingone.com/as/token

Note: PingOne platform scopes such as the p1:read:env:user scope cannot be modified or deleted. However, you can create custom scopes. When you create a custom scope, the POST /environments/{envId}/resources/{resId}/scopes request URL requires an environment ID and a resource ID to associate the new scope with a resource entity.

The examples below show common actions to find and manage scopes. You need the Client Application Developer role to perform operations on scopes resources. For more information, see Work with user roles.

Get scopes

The GET /environments/{environmentId}/scopes endpoint returns a list of all PingOne platform scopes associated with the specified environment resource.

curl -X "GET" "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261/scopes" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261/scopes"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261"
        }
    },
    "_embedded": {
        "scopes": [
            {
                "id": "2f465a3a-331e-44db-8c34-f9b3909bb388",
                "resource": {
                    "id": "79d29353-1508-4276-b0fa-2bffd5566aed"
                },
                "name": "phone",
                "description": "",
                "platform": true
            },
            {
                "id": "5cceac35-9df1-47e3-b858-b6547c42c2b2",
                "resource": {
                    "id": "79d29353-1508-4276-b0fa-2bffd5566aed"
                },
                "name": "email",
                "description": "",
                "platform": true
            },
            {
                "id": "afb8948c-849c-481c-8078-903084729ae4",
                "resource": {
                    "id": "79d29353-1508-4276-b0fa-2bffd5566aed"
                },
                "name": "profile",
                "description": "",
                "platform": true
            },
            {
                "id": "1a15cff1-5c6f-461e-a61f-c890dab58708",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:update:env:userPassword",
                "description": "",
                "platform": true
            },
            {
                "id": "24d37aff-8b68-4f8c-83d3-415a1f9553c5",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:userPasswordState",
                "description": "",
                "platform": true
            },
            {
                "id": "2f319a2c-89ca-45b8-8b83-ca4ea682c256",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:passwordPolicy",
                "description": "",
                "platform": true
            },
            {
                "id": "3b599292-e801-44e1-8483-4500674250a9",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:delete:env:population",
                "description": "",
                "platform": true
            },
            {
                "id": "46291f94-dd0d-43c1-9fe3-94cb26d89824",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:import:env:user",
                "description": "",
                "platform": true
            },
            {
                "id": "5c6ab6ef-adad-4c99-bfac-fc950cc57707",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:activity",
                "description": "",
                "platform": true
            },
            {
                "id": "6710967d-5b4c-40e2-8fd4-8334f6d7f58c",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:update:env:branding",
                "description": "",
                "platform": true
            },
            {
                "id": "6abae16e-6563-48cb-8718-0ff510459844",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:validate:env:userPassword",
                "description": "",
                "platform": true
            },
            {
                "id": "722e17dc-cfb8-4cf1-8aa3-8e8042d0d2f0",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:create:env:population",
                "description": "",
                "platform": true
            },
            {
                "id": "73577f93-4c73-47fb-a01e-4c3855d807ad",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:delete:env:user",
                "description": "",
                "platform": true
            },
            {
                "id": "7fa401a8-db13-4b29-94bd-e3c8566998d1",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:update:env:user",
                "description": "",
                "platform": true
            },
            {
                "id": "8dea2cb1-7f85-43e0-a303-23d391924e80",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:update:env:population",
                "description": "",
                "platform": true
            },
            {
                "id": "9b90184a-1120-4638-8592-574cbb08c9d6",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:update:env:passwordPolicy",
                "description": "",
                "platform": true
            },
            {
                "id": "a583a606-f3eb-4ef6-884f-72aca28e9e39",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:delete:env:branding",
                "description": "",
                "platform": true
            },
            {
                "id": "b88aa862-2c5d-4c7c-9ef7-36b2a3ab645a",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:org:organization",
                "description": "",
                "platform": true
            },
            {
                "id": "c24ff356-9daa-47c6-a421-5b0afbd1e28d",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:user",
                "description": "",
                "platform": true
            },
            {
                "id": "cad2d85c-2830-4633-a188-aeec7e22aeb6",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:environment",
                "description": "",
                "platform": true
            },
            {
                "id": "d63384b7-a270-4af2-8a6f-d2c0efd10579",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:read:env:population",
                "description": "",
                "platform": true
            },
            {
                "id": "f3db5068-70c9-452e-a58a-d157ad1b206c",
                "resource": {
                    "id": "607d2326-5d08-475d-aab3-8e8df5237c18"
                },
                "name": "p1:create:env:user",
                "description": "",
                "platform": true
            }
        ]
    },
    "size": 22
}

To get data for a single scope resource, the GET /environments/{envId}/resources/{resId}/scopes/{id} operation returns data for the scope resource with the specified user ID.

curl -X GET "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/resources/2c820676-3f02-49fe-b3c6-0fd854e53d4e/scopes/{id}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

Create scopes

The POST /environments/{envId}/resources/{resId}/scopes operation adds a new scope. The request URL specifies the new scope’s associated environment ID and resource ID.

curl -X "POST" "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/resources/2c820676-3f02-49fe-b3c6-0fd854e53d4e/scopes/" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "photoapp:MyNewScope"
}'

The request body must specify a value for the scope name property, and the name value must be unique within the specified environment resource.

Update scopes

The PUT /environments/{envId}/resources/{resId}/scopes/{id} operation updates the property values of the identified scope.

curl -X "PUT" "https://api.pingone.com/v1/environments/58f92121-b753-4e7e-8d82-23b5bf80efe5/resources/2c820676-3f02-49fe-b3c6-0fd854e53d4e/scopes{id}/" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "photoapp:edit:photos",
  "description": "Allows users to edit their photo files."
}'

The request body specifies updated values for the scope name and description properties. Any property values not specified in the request body are cleared. The response returns a 200 OK message, and it shows the updated property data for the modified scope resource.