Resources


Resources

Resources are the protected endpoints that applications request access to using OAuth 2 authorization services. For example, https://api.pingone.com is a defined resource that represents the PingOne for Customers APIs. PingOne also defines an openid resource that uses OpenID Connect scopes with the /{environmentId}/as/userinfo endpoint to request specific sets of information as claim values in the ID token. For more information about the userinfo endpoint requests, see Userinfo authorization requests. You can also define custom resources to associate with applications.

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, a user resource with an access token that includes the p1:read:user scope has read access to it own user resource data.

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:

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:user&acr_values=Single_Factor'

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

curl --request GET \
  --url 'https://auth.pingone.com/{environmentID}/as/authorize?response_type=code&client_id={appID}&redirect_uri=https://example.com&scope=p1:read:user p1:update:user p1:reset:userPassword&acr_values=Single_Factor'

Note: PingOne platform scopes such as the p1:read: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 that follow show common actions to find and manage resources entities. You need the Client Application Developer role to perform operations on resources entities.

Resources API operations

The resources endpoints support the following operations:

For hands-on experience with the resources API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Resources data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the resource.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the resource’s unique identifier.
name A string that specifies the resource name, which must be provided and must be unique within an environment.
type A string that specifies the type of resource. Options are PLATFORM and CUSTOM.
updatedAt The time the resource was last updated.

Scopes data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the scope.
environment.id A string that specifies the environment resource’s unique identifier associated with the resource.
id A string that specifies the scope resource’s unique identifier.
name A string that specifies the resource name.
resource.id A string that specifies the unique identifier of the resource entity associated with the scope.
updatedAt The time the resource was last updated.

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.

Endpoint examples

Get resources

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

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/resources" \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
  "_links" : {
    "self" : {
      "href" : "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261/resources"
    }
  },
  "_embedded" : {
    "items" : [ {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261/resources/607d2326-5d08-475d-aab3-8e8df5237c18"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261"
        }
      },
      "id" : "607d2326-5d08-475d-aab3-8e8df5237c18",
      "name" : "https://api.pingone.com",
      "description" : "APIs to manage all aspects of the PingOne platform."
    }, {
      "_links" : {
        "self" : {
          "href" : "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261/resources/79d29353-1508-4276-b0fa-2bffd5566aed"
        },
        "environment" : {
          "href" : "https://api.pingone.com/v1/environments/0271641f-2d74-4bb0-b416-4a39b8714261"
        }
      },
      "id" : "79d29353-1508-4276-b0fa-2bffd5566aed",
      "name" : "openid",
      "description" : "OpenID Connect scopes can be used to request that specific sets of information be made available as Claim Values in the ID token and the userinfo endpoint."
    } ]
  },
  "count" : 2,
  "size" : 2
}

Get one resource

To get data for a single resource entity, the GET /environments/{environmentId}/resources/{resourceId} operation returns data for the resource entity with the specified ID.

curl -X GET "https://api.pingone.com//v1/environments/{environmentId}/resources/{resourceId}" \
-H "Authorization: Bearer jwtToken"

Create resources

The POST /environments/{environmentId}/resources operation adds a new resource entity to the specified environment resource.

curl -X "POST" "https://api.pingone.com/v1/environments/{environmentId}/resources" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "MyNewResource"
}'

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

Update resources

The PUT /environments/{environmentId}/resources/{resourceId} operation updates the property values of the identified resource entity.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken' \
-d $'{
  "name": "https://api.photostore.com",
  "description": "Resource for PhotoStore application endpoints."
}'

The request body specifies updated property values for the resource name and description. 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 resource entity.

Delete resources

The following sample shows the DELETE /environments/{environmentId}/resources/{resourceId} operation to delete the resource entity specified by its ID in the request URL.

curl -X DELETE "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede" \
-H "Authorization: Bearer jwtToken"

When successful, the DELETE request returns a code 204 No Content message.

Get scopes for a resource

To get the list of scopes associated with a specified resource, the GET /environments/{environmentId}/resources/{resourceId}/scopes operation returns data for the scopes associated with the resource entity ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/scopes" \
-H "Authorization: Bearer jwtToken"

Note: To get all scopes for all resources, you can use GET /environments/{environmentId}/resources with the ?expand=scopes query parameter appended to the request. The response data lists all scopes and shows the scope sub-resource data in the _embedded section of the response.

Get one scope

To get data for a single scope resource, the GET /environments/{environmentId}/resources/{resourceId}/scopes/{scopeId} operation returns data for the scope resource identified by its ID in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/scopes/{scopeId}" \
-H "Authorization: Bearer jwtToken"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/resources/3dd4ac35-f06a-4569-90b7-a5e3dba6b4d2/scopes/a0a346fb-3866-4100-89d9-cb9e88bc9638"
        },
        "resource": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca/resources/3dd4ac35-f06a-4569-90b7-a5e3dba6b4d2"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
        }
    },
    "id": "a0a346fb-3866-4100-89d9-cb9e88bc9638",
    "environment": {
        "id": "5da98f13-ad62-4234-ba04-2b6e2e85c8ca"
    },
    "resource": {
        "id": "3dd4ac35-f06a-4569-90b7-a5e3dba6b4d2"
    },
    "name": "p1:read:user",
    "description": "Ability for the user to retrieve their own user identity and all attributes"
}

Create scopes

The POST /environments/{envId}/resources/{resourceId}/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/{environmentId}/resources/{resourceId}/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/{environmentId}/resources/{resourceId}/scopes/{scopeId} operation updates the property values of the identified scope.

curl -X "PUT" "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/scopes/{scopeId}/" \
-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.

Delete scopes

The following sample shows the DELETE /environments/{environmentId}/resources/{resourceId}/scopes/{scopeId} operation to delete the scope.

curl -X DELETE "https://api.pingone.com/v1/environments/{environmentId}/resources/{resourceId}/scopes/{scopeId}" \
-H "Authorization: Bearer jwtToken"

When successful, the DELETE request returns a code 204 No Content message.