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.

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
accessTokenValiditySeconds An integer that specifies the number of seconds that the access token is valid. If a value is not specified, the default is 3600. The minimum value is 300 seconds (5 minutes); the maximum value is 2592000 seconds (30 days).
audience A string that specifies a URL without a fragment or “@ObjectName” and must not contain “pingone” or “pingidentity” (for example, https://api.myresource.com). If a URL is not specified, the resource name is used.
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 OPENID_CONNECT, PING_ONE_API, and CUSTOM. Only the CUSTOM resource type can be created. OPENID_CONNECT specifies the built-in platform resource for OpenID Connect. PING_ONE_API specifies the built-in platform resource for PingOne.
updatedAt The time the resource was last updated.

Resources core attribute data model

Property Description
sub A string that specifies the core claim for the new resource. The default value is ${user.id}.

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/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources"
    }
  },
  "_embedded": {
    "resources": [
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/b6f08ba7-a50b-44f0-922f-91c03f0390f8"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "scopes": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/b6f08ba7-a50b-44f0-922f-91c03f0390f8/scopes"
          }
        },
        "id": "b6f08ba7-a50b-44f0-922f-91c03f0390f8",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "name": "JB_Custom",
        "description": "This is a custom resource",
        "type": "CUSTOM",
        "audience": "https://api.jb.com",
        "createdAt": "2019-08-19T16:51:41.416Z",
        "updatedAt": "2019-08-19T17:09:39.232Z",
        "accessTokenValiditySeconds": 3600
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/faac7db8-67ce-44aa-8ae0-5ae672f5b8bf"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "scopes": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/faac7db8-67ce-44aa-8ae0-5ae672f5b8bf/scopes"
          }
        },
        "id": "faac7db8-67ce-44aa-8ae0-5ae672f5b8bf",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "name": "https://api.pingone.com",
        "description": "APIs to manage all aspects of the PingOne platform.",
        "type": "CORE",
        "audience": "https://api.pingone.com"
      },
      {
        "_links": {
          "self": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/e303cdcd-2fce-4181-90a9-ff945280ae4a"
          },
          "environment": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
          },
          "scopes": {
            "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/e303cdcd-2fce-4181-90a9-ff945280ae4a/scopes"
          }
        },
        "id": "e303cdcd-2fce-4181-90a9-ff945280ae4a",
        "environment": {
          "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
        },
        "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.",
        "type": "CORE",
        "audience": "https://api.pingone.com"
      }
    ]
  },
  "count": 3,
  "size": 3
}

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": "CustomResource1",
  "description": "This is my custom resource",
  "audience": "https://api.custom.com",
  "accessTokenValiditySeconds": 7200
}'

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. If a value for the accessTokenValiditySeconds property is not specified, the new resource uses the default value of 3600 seconds. If a value for the audience property is not specified, the value defaults to the name of the resource.

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/54509d14-5248-4598-b80c-20dfa8d96cea"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "scopes": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/54509d14-5248-4598-b80c-20dfa8d96cea/scopes"
    }
  },
  "id": "54509d14-5248-4598-b80c-20dfa8d96cea",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "name": "CustomResource1",
  "type": "CUSTOM",
  "audience": "https://api.custom.com",
  "description": "This is my custom resource",
  "createdAt": "2019-08-19T19:31:43.875Z",
  "updatedAt": "2019-08-19T19:31:43.875Z",
  "accessTokenValiditySeconds": 7200
}

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": "CustomResource_EU",
  "audience": "https://api.custom.eu"
}'

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

The response data looks like this:

{
  "_links": {
    "self": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/b6f08ba7-a50b-44f0-922f-91c03f0390f8"
    },
    "environment": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
    },
    "scopes": {
      "href": "https://api.pingone.com/v1/environments/9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7/resources/b6f08ba7-a50b-44f0-922f-91c03f0390f8/scopes"
    }
  },
  "id": "b6f08ba7-a50b-44f0-922f-91c03f0390f8",
  "environment": {
    "id": "9ad15e9e-3ac6-43f7-a053-d46b87d6c4a7"
  },
  "name": "CustomResource_EU",
  "type": "CUSTOM",
  "audience": "https://api.custom.eu",
  "createdAt": "2019-08-19T16:51:41.416Z",
  "updatedAt": "2019-08-19T19:23:31.098Z",
  "accessTokenValiditySeconds": 3600
}

In this example, the description property value was cleared. The accessTokenValiditySeconds property value was cleared and reset to the default value of 3600. The name and audience properties were modified to the values specified in the request body.

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/{environmentId}/resources/{resourceId}" \
-H "Authorization: Bearer jwtToken"

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