PingOne Platform APIs

Credential Signing Keys

You can choose to sign credentials before issuance using your private keys maintained within your infrastructure. However, to properly build the JWT header, Ping Identity requires your public key.

Use the Credential Signing Keys operations to store, retrieve, update, or delete the public signing keys used when communicating credentials between you and Ping Identity for signing before issuing.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Credential signing key data model

Property Type Required Mutable Description

createdAt

DateTime

N/A

Read-only

Date and time the credential signing key was created.

enabled

String

Required

Mutable

Whether the key is available for use in signing. Allows you to change the key that is used by the credentialing service for signing but retain the key for verification. Can be true or false.

environment.id

String

N/A

Read-only

PingOne environment identifier (UUID) in which the credential signing key exists.

jwk

Object

Required/Optional

Immutable

JSON Web Key as defined in RFC 7517. Required for Create Customer Signing Public Key, but optional (because it is immutable) for Update Customer Signing Public Key. Used when sending unsigned credentials to your signing endpoint and verifying returned signed credentials.

jwk.alg

String

Required

Immutable

Algorithm, identifies the algorithm intended for use with the key. Refer to Available algorithms for JWK.

jwk.crv

String

Required/Optional

Immutable

Curve of the Elliptic Curve (EC) or Octet Key Pair (OKP) public key. Required for EC- and OKP-based algorithms, optional and ignored if present for other algorithms.

jwk.e

String

Required/Optional

Immutable

RSA exponent of the RSA public key. Required for RSA-based algorithms, optional and ignored if present for other algorithms.

jwk.kid

String

Required

Immutable

Key ID, a unique identifier for the key that helps when selecting a key.

jwk.kty

String

Required

Immutable

Key Type, identifies the cryptographic algorithm family used with the key. Can be RSA, EC, or OKP.

jwk.n

String

Required/Optional

Immutable

RSA modulus of the RSA public key. Required for RSA-based algorithms, optional and ignored if present for other algorithms.

jwk.x

String

Required/Optional

Immutable

Elliptic curve x-coordinate of the EC public key or OKP public key. Required for EC-based algorithms and OKP-based algorithms, optional and ignored if present for other algorithms.

jwk.y

String

Required/Optional

Immutable

Elliptic curve y-coordinate of the EC public key. Required for EC-based algorithms, optional and ignored if present for other algorithms.

name

String

Optional

Mutable

A friendly name shown in the admin console for the key. Optional and defaults to jwk.kid.

updatedAt

DateTime

N/A

Read-only

Date and time the credential signing key was last updated. Can be null.

The jwk object must not contain private key material. If you perform a POST request and the jwk object includes private key material, the service returns an HTTP 400 error.

The key ID, jwk.kid, accepts up to 256 characters from the set: a-z, 0-9, A-Z, -, and _ and must be unique within an environment. Attempted reuse of a kid returns an error.

The service allows multiple keys with enabled set to true. However, the service selects a key to use from the available keys.

All keys, regardless of enabled state, are included in did:web responses so that the key can be used for verifying an issued credential.

Available algorithms for JWK

The service does not allow none.

Key Management Algorithm jwk.alg

RSAES-PKCS1-V1_5 key encryption

RSA1_5

RSAES using OAEP key encryption

RSA-OAEP

RSA-OAEP-256

AES key wrap

A128KW

A192KW

A256KW

AES GCM key encryption

A128GCMKW

A192GCMKW

A256GCMKW

Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF

ECDH-ES

Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF with AES key wrap

ECDH-ES+A128KW

ECDH-ES+A192KW

ECDH-ES+A256KW

Credential Signing Keys errors

In addition to the general error codes, credential signing key operations can return the following errors:

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

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 /credentialSigningKeys request supplies a jwk object that cannot be parsed as a JSON Web Key, such as a missing kty or a missing key field for the key type, or a path identifier cannot be parsed as a UUID

Details: The jose4j parsing message for the failing field with the target at the jwk field path, for example Missing required 'kty' parameter. or Missing required 'n' parameter.

400

INVALID_DATA

REQUIRED_VALUE

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

When and details

When: A POST /credentialSigningKeys request omits the jwk object

Details: jwk must not be null, reported against the jwk property

400

INVALID_DATA

INVALID_VALUE or OUT_OF_RANGE

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

When and details

When: A POST or PUT /credentialSigningKeys request supplies a jwk object with a missing or blank alg, a kid that is missing, contains characters outside a-z, 0-9, A-Z, -, and _, or is longer than 256 characters, an alg that the service does not support (such as none), a jwk.kty that does not match jwk.alg, or a jwk that contains private key material, or supplies a name that is blank, contains characters outside Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens, or is longer than 256 characters

Details: The validator literal for the failing property, for example alg must not be null or empty for a blank jwk.alg, kid must not be null for an omitted jwk.kid, kid must contain only alphanumeric characters, dashes, and underscores for a jwk.kid with invalid characters, kid must not be longer than 256 characters for an overly long jwk.kid, unsupported algorithm: <alg> for an unsupported jwk.alg, key type <kty> does not match algorithm <alg> for a mismatched key type and algorithm, must not contain private key material for a jwk that includes a private key field, must not be empty or blank for a blank name, or must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for a name with invalid characters (for example Validation Error : [jwk kid must not be null]). A name longer than 256 characters returns size must be between 1 and 256 with rangeMinimumValue and rangeMaximumValue inner errors and the OUT_OF_RANGE detail code

400

INVALID_DATA

UNIQUENESS_VIOLATION

Message: A resource with the specified name already exists.

When and details

When: A POST /credentialSigningKeys request supplies a jwk.kid that already exists in the environment

Details: CredentialSigningKey with kid <kid> already exists in environment, reported against the jwk.kid property

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: The environment does not have the capability to use PingOne Credentials

Details: Environment does not have capability to use credentials

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 PUT /credentialSigningKeys/{credentialSigningKeyID} request supplies a jwk object that differs from the existing key

Details: The attribute is immutable and can not be updated. for the jwk property

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the credentialsIssuance:create:credentialSigningKey permission (POST), the credentialsIssuance:read:credentialSigningKey permission (GET), the credentialsIssuance:update:credentialSigningKey permission (PUT), or the credentialsIssuance:delete:credentialSigningKey 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 /credentialSigningKeys/{credentialSigningKeyID} request references a credential signing key that does not exist in the environment

Details: None

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The service encounters an internal error while processing the request.

Details: None