PingOne Platform APIs

Resource Secret

The client secret endpoint is available to users or worker resources only if they have a superset of the resource’s role assignments.

Access to the resource’s client secret is restricted based on the accessing user’s or resource’s role assignments. For example, if a client has the Environment Admin role, an actor with an Identity Admin role cannot see the client secret. This restriction addresses privilege escalation issues by preventing the Identity Admin user from doing things with the client that the Identity Admin role assignment does not allow.

Best practices

  • Do not store a resource’s client secret in applications that are publicly available.

  • For security purposes, regenerate client secrets regularly.

  • If you suspect a resource’s client secret has been compromised, generate a new client secret immediately.

Resource client secret data model

Property Type Required Mutable Description

environment.id

String

Read-only

The environment associated with the resource.

previous

Object

Optional

Read only

An object that specifies the resource’s previous secret, when it expires, and when it was last used.

previous.secret

String

N/A

Read only

A string that specifies the resource’s previous secret. This property is returned in the response if the previous secret is not expired.

previous.expiresAt

Timestamp

Optional

Read only

A timestamp that specifies how long this secret is saved (and can be used) before it expires. Supported time range is 1 minute to 90 days.

previous.lastUsed

Timestamp

Optional

Read only

A timestamp that specifies when the previous secret was last used.

secret

String

N/A

Read-only

An auto-generated resource client secret. Possible characters are a-z, A-Z, 0-9, -, ., _, ~. The secret has a minimum length of 64 characters per SHA-512 requirements when using the HS512 algorithm to sign ID tokens using the secret as the key.

Resource client secret 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.

Resource secret errors

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

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

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [previous.expiresAt Invalid secret expiry date]

When and details

When: A POST request supplies a previous.expiresAt value that is not between 1 minute and 90 days in the future (30 days when the environment does not have the 90-day retention feature enabled)

Details: Invalid secret expiry date

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 request with application/vnd.pingidentity.secret+json supplies a secret shorter than 8 or longer than 1024 characters, containing characters outside the allowed set, or omits the secret property

Details: Validation Error : [clientSecret size must be between 8 and 1024], Invalid resource, invalid client secret., or Invalid request, admin-defined client secret is required.

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

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

When and details

When: The actor is not authorized for the environment in the request URL (the actor’s role assignments are not a superset of the resource’s role assignments)

Details: Access is denied

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the resources:read:secret permission (GET), the resources:update:secret permission (POST with application/json or without a request body), the resources:set:secret permission (POST with application/vnd.pingidentity.secret+json), or the resources:delete:secret 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, POST, or DELETE request references a resource ID that does not exist in the environment, targets a built-in platform resource (PING_ONE_API or OPENID_CONNECT), or the set-secret operation is used when the admin-defined update secret feature flag is off for the environment

Details: None.