PingOne Platform APIs

Resource Operations

The /resources endpoint provides operations to create, read, update, and delete resource entities. The examples that follow show common actions to find and manage resources entities.

You need the Environment Admin or the Client Application Developer roles to perform operations on resources entities.

Importing external resources to PingOne

Environment Admins can import resources to PingOne, preserving the existing resource client ID and client secret. This enables you to:

  • Replicate resource records that have been created in another platform.

  • Recover from an accidental deletion of a resource. You can create a new resource record using the client ID and client secret of the deleted resource.

Import of resources is supported only by Import Resource, and specifying clientId and clientSecret in the request body. You’re also able to import OIDC applications to PingOne. Refer to Importing external OIDC applications to PingOne for more information.

Resources data model

Property Type Required Mutable Description

accessTokenValiditySeconds

Integer

Required

Mutable

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).

applicationPermissionsSettings

Object

Optional

Mutable

For custom resources, when an application has requested an access token scoped to the Resource service on behalf of a user, and the Resource service has application permissions enabled, this object enables adding the user’s application permissions to the access token generated by PingOne.

applicationPermissionsSettings.claimEnabled

Boolean

Optional

Mutable

For custom resources, when enabled this is true, the access token includes a claim with an array of the permissions assigned to the user. If an application requests an access token for the Resource service that does not have the permissions option enabled, the token will not include permissions assigned to the user. See PingOne Permissions by Resource or PingOne Permissions by Identifier for more information. If this property is omitted, the value is set to false.

audience

String

Required

Mutable

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. The value that you set here is returned in the audience claim in the token. For more information, refer to Token Introspection (Resource ID and Secret).

clientId

String

Optional

Immutable

(Required when clientSecret is specified.) Supported only for POST operations. If an identifier exists for an external resource that’s being imported to PingOne, this identifier can be set here. This must be a minimum of 8 alpha-numeric characters (maximum 256), and must be globally unique in PingOne. If an identifier for an external resource doesn’t exist when it’s imported to PingOne, the id value automatically generated for the resource is used as the identifier.

clientSecret

String

Optional

Immutable

Supported only for POST operations. This is the client secret associated with clientId for an external resource that is being imported to PingOne. This must be a minimum of 8 alpha-numeric characters, and a maximum of 1024 characters. This value is encrypted by PingOne, and returned by the POST, GET, and PUT requests. When a client secret is not provided, PingOne generates a client secret as part of the resource-creation process. In this case, you’ll need to update the generated client secret with a new one using Set Resource Client Secret (Imported Resource).

createdAt

Date

N/A

Read only

The time the resource was created.

description

String

Optional

Mutable

Description of the resource.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the resource.

id

String

Required

Immutable

The resource’s unique identifier.

name

String

Required

Immutable

The resource name, which must be provided and must be unique within an environment.

introspectEndpointAuthMethod

String

Required

Mutable

The authentication methods supported by the token endpoint. Options are NONE, CLIENT_SECRET_BASIC, CLIENT_SECRET_POST, CLIENT_SECRET_JWT, and PRIVATE_KEY_JWT. Applicable only to custom resources.

type

String

Required

Mutable

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

Date

N/A

Read only

The time the resource was last updated.

Resources core attribute data model

Property Type Required Mutable Description

sub

String

Required

Mutable

The core claim for the new resource. The default value is ${user.id}.

Resources events generated

Refer to 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.

Resources errors

In addition to the general error codes, resource operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<field> <message>]

When and details

When: A POST or PUT request body omits name, or supplies a name, audience, or description value that fails validation

Details: Describes the failing property, such as must not be empty for an omitted or empty name, or:

must 1) only contain Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens, or 2) be a valid absolute URI that does not contain the substrings "pingidentity" or "pingone", or 3) not use reserved name PingOne API

for an invalid name or audience value, for example:

Validation Error : [name must 1) only contain Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens, or 2) be a valid absolute URI that does not contain the substrings "pingidentity" or "pingone", or 3) not use reserved name PingOne API]

400

INVALID_DATA

OUT_OF_RANGE

Message: Validation Error : [<field> <message>]

When and details

When: A POST or PUT request sets accessTokenValiditySeconds outside the range of 300 to 2592000 seconds

Details: accessTokenValiditySeconds with must be between 300 and 2592000; the detail includes innerError values for the minimum and maximum, for example Validation Error : [accessTokenValiditySeconds must be between 300 and 2592000].

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request specifies a name or audience value already used by another resource in the environment (the audience check also matches other resources' custom client IDs and application client IDs)

Details: A resource with the specified name already exists. with target name or audience and an existingId inner error carrying the conflicting resource’s or application’s ID

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST request that specifies clientId (resource import) uses a client ID already assigned to another resource or application

Details: A resource with the specified client id already exists. or An application with the specified client id already exists. (each on target clientId with an existingId inner error carrying the conflicting resource’s or application’s ID)

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request names the resource OpenID Connect (case-insensitive)

Details: Resource name 'OpenID Connect' is reserved for system use. with target name

400

INVALID_DATA

INVALID_VALUE or REQUIRED_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST request that specifies clientId or clientSecret (resource import) supplies values that are too short, too long, or contain unsupported characters, or supplies a clientSecret without an admin‑defined clientId

Details: Validation Error : [clientId size must be between 8 and 256], Invalid resource, client id does not match expected format., The provided clientId matches a reserved clientId in this environment and cannot be used. (each on target clientId), Validation Error : [clientSecret size must be between 8 and 1024], Invalid resource, invalid client secret. (each on target client_secret), or Invalid resource, admin-defined client id is required. (detail code REQUIRED_VALUE, target client_id)

400

INVALID_DATA

CONSTRAINT_VIOLATION

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT request sets introspectEndpointAuthMethod to PRIVATE_KEY_JWT and omits both jwksUrl and jwks, sets both jwksUrl and jwks, or sets audience to https://api.pingone.com outside the internal allowlist

Details: jwksUrl or jwks is required when introspectEndpointAuthMethod=PRIVATE_KEY_JWT or jwksUrl and jwks cannot both be set (each on target jwksUrl), or Audience value is not allowed for this environment. (on target audience)

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST or PUT request sets introspectEndpointAuthMethod to a value that is not one of the supported authentication methods

Details: Invalid value for attribute. with target introspectEndpointAuthMethod

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A PUT or DELETE request targets a built-in platform resource (PING_ONE_API or OPENID_CONNECT)

Details: The resource '<id>' cannot be modified. with no target

400

REQUEST_FAILED

ITEM_LIMIT_EXCEEDED

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST request exceeds the environment’s custom resource limit (default 1000, adjustable by feature flag)

Details: Cannot create more than <limit> custom resources for environment <environmentId> with no target

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: A POST or PUT request sets applicationPermissionsSettings.claimEnabled to true in an environment that does not have the Application Permissions capability

Details: You do not have permissions or are not licensed to make this request. with target applicationPermissionsSettings.claimEnabled

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the resources:create:resource permission (POST), the resources:read:resource permission (GET), the resources:update:resource permission (PUT), or the resources:delete:resource permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: A GET, PUT, or DELETE request references a resource ID that does not exist in the environment

Details: None.