PingOne Platform APIs

Certificate Management

The certificate management service manages two types of records, keys and certificates. Keys represent a key pair that consists of a private key and a public key. A certificate represents the electronic document used to verify the owner of the public key. This service supports FIPS 140-2 Level 1 compliant security algorithms to generate key pairs, and manages:

  • Customer-provided certificates

  • Customer-provided signing and encryption keys

  • PingOne-generated certificates (PKI)

  • PingOne-generated signing and encryption keys

  • Key rotation policies

The certificate management service also manages encryption and decryption operations, as well as signing and validation operations.

To use any of the PingOne signing and encryption features, you’ll need to either provide a certificate you’ve generated, or configure the options for a PingOne-signed certificate. When uploading certificates, the certificate must be valid at the time of upload. You cannot upload a certificate before its validity period begins (the certificate’s NotBefore date), or after it expires (the certificate’s NotAfter date). The private key must be unencrypted. You cannot upload a private key that is protected by a password or passphrase. The certificate, private key, and certificate chain must all be PEM-encoded unless uploading a PKCS12 file format.

For endpoints that return binary data, it is recommended that clients use the Accept request header to specify that the client can also receive an application/json response (for example, Accept: application/x-x509-ca-cert, application/json). This addition to the Accept header prevents 404 NOT_FOUND errors that can be returned by the API gateway as 500 UNEXPECTED_ERROR messages.

Default organization and environment certificates

The certificate management service creates default certificates for PingOne organization, and environment resources.

Default organization certificate

The certificate management service listens for the "create organization" event, and when the organization is created, the certificate management service creates a default intermediate CA signing certificate for the organization resource. This default org certificate is used to sign all environment certificates.

The default organization certificate includes the following values:

Property Value

version

V3 (2)

serialNumber

Secure Random generated

algorithmID

sha256WithRSAEncryption

issuer

commonName: Ping Identity v2; organizationalUnit: www.pingidentity.com; organization: Ping Identity Corporation; country: US

subject

commonName: value; Organization Name: value; organizationalUnit: value; organization: value; country: value

validity

not before: current date, not after: 1 year from current date

extensions

none

Default environment certificate

The service also listens for "create environment" events and creates the default key and certificate for the environment resource. The default organization certificate signs all environment certificates.

The default environment certificate includes the following values:

Property Value

version

V3 (2)

serialNumber

Secure Random generated

algorithmID

sha256WithRSAEncryption

Default environment key

The default environment key includes the following values:

Property Value

algorithm

RSA

validity period

1 year

key length

2048

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.

Certificate management data model

Property Type Required Mutable Description

algorithm

String

Required

Immutable

The key algorithm. Options are RSA, EC, and UNKNOWN.

createdAt

Date

N/A

Read-only

The time the resource was created.

default

Boolean

Required

Mutable

Indicates whether this is the default key for the specified environment.

environment.id

String

Required

Immutable

Specifies the environment resource’s unique identifier.

expiresAt

Date

N/A

Read-only

The time the key resource expires.

id

String

Required

Immutable

The resource’s unique identifier.

issuerDN

String

Required

Mutable

The distinguished name (DN) of the certificate issuer.

keyLength

Integer

Required

Immutable

The key length. For RSA keys, options are 2048, 3072, 4096, and 7680. For elliptical curve (EC) keys, options are 224, 256, 384, and 521.

name

String

Optional

Mutable

The resource name.

organization.id

String

Required

Immutable

The organization resource’s unique identifier.

serialNumber

Integer

Required

Immutable

The serial number of the key or certificate.

signatureAlgorithm

String

Required

Immutable

The signature algorithm of the key. Options are SHA256withRSA and SHA512withRSA.

startsAt

Date

Required

Immutable

The time the validity period starts.

status

String

N/A

Read-only

The status of the key. Options are VALID, EXPIRED, NOT_YET_VALID, and REVOKED. If the current time is within 2 weeks of the expiration date, the status is EXPIRING.

subjectDN

String

Required

Immutable

The DN of the subject being secured.

trustChain

String[]

Optional

Mutable

An array of PEM-encoded X509 Certificates that are in the trust chain of the key’s chain of trust.

usageType

String

Required

Mutable

Specifies how the certificate is used. Options are ENCRYPTION, SIGNING, ISSUANCE, SSL_TLS, and OUTBOUND_MTLS. ISSUANCE keys are used as part of another key’s trust chain, and are used to sign other keys. Certificate Revocation Lists (CRL) are published against these keys. SSL_TLS keys are used to protect internet protocol domains (such as, a Custom Domain you’ve configured in PingOne). OUTBOUND_MTLS keys are used to enable mutual TLS (mTLS) authentication with a subscription service.

validityPeriod

Integer

Required

Immutable

The number of days the key is valid.

Certificates and keystore 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.

404

The requested resource was not found.

Certificate management errors

In addition to the general error codes, certificate management 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, INVALID_VALUE, or OUT_OF_RANGE

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

When and details

When: A POST /keys request omits a required property (algorithm, signatureAlgorithm, subjectDN, or usageType), or supplies a value that violates the data model — a usageType that is not SIGNING, ENCRYPTION, ISSUANCE, SSL/TLS, or OUTBOUND_MTLS, a signatureAlgorithm that is not valid for the algorithm, a keyLength that is not valid for the signatureAlgorithm, a serialNumber or keyLength that is not greater than 0, a validityPeriod outside the range 0 to 999999, a subjectDN or issuerDN that is not a valid Distinguished Name, a name that contains invalid characters or exceeds 256 characters, or an expiresAt that is not after startsAt

Details: must not be null for an omitted algorithm, signatureAlgorithm, or usageType, must not be blank for an omitted or blank subjectDN, must be greater than 0 for a serialNumber or keyLength that is not greater than 0, must be greater than or equal to 0 for an expiresAt that is not after startsAt, or is not a valid Distinguished Name (DN) for an invalid subjectDN or issuerDN, for example Validation Error : [usageType must not be null].

400

INVALID_DATA

None

Message: Key default must be set to SIGNING or ENCRYPTION to update

When and details

When: A PUT /keys/{keyID} request sets usageType to a value other than SIGNING or ENCRYPTION

Details: None.

400

INVALID_DATA

None

Message: Failed to open PKCS12 file, it may be encrypted

When and details

When: A POST /keys request uploads an encrypted pkcs12 file with a missing or incorrect export password

Details: None.

400

INVALID_DATA

None

Message: Failed to create PKCS12 key (public/private keypair is not valid)

When and details

When: A POST /keys request uploads a pkcs12 file whose public and private keys do not form a valid pair

Details: None.

400

INVALID_REQUEST

None

Message: Certificate in trust chain is expired or Certificate in trust chain is not yet valid.

When and details

When: A POST /keys request uploads a pkcs12 file containing a certificate in the trust chain that is outside its validity period

Details: None.

400

INVALID_REQUEST

INVALID_VALUE

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

When and details

When: A request supplies a property value that cannot be deserialized — an unknown enumeration value or a value of the wrong JSON data type

Details: Invalid value for attribute.

400

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

CONSTRAINT_VIOLATION

Message: <operation>.<cross-parameter>: <message>, for example deleteKeyForEnvironmentById.<cross-parameter>: The Key must not be in use

When and details

When: A DELETE /keys/{keyID} request targets a key that is in use by an application, identity provider, or subscription, or targets the environment’s default key, a DELETE /certificates/{certID} request targets a certificate that is in use, or a POST /keys request exceeds the environment’s key limit (100 keys, overridable per environment through a feature flag)

Details: The Key must not be in use (in-use key), The Key must not be default (default key), The Certificate must not be in use (in-use certificate), or Environment with ID <envID> has reached its maximum limit of <limit> Keys (key limit)

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the certmgt:create:key permission (POST /keys and the CA-reply import PUT or POST /keys/{keyID}/csr), the certmgt:read:key permission (key GET operations and GET /keys/{keyID}/csr), the certmgt:update:key permission (PUT /keys/{keyID}), the certmgt:issue:certificate permission (POST /keys/{keyID}/issuance), the certmgt:create:certificate permission (POST /certificates), the certmgt:read:certificate permission (certificate GET operations), the certmgt:delete:key permission (DELETE /keys/{keyID}), or the certmgt:delete:certificate permission (DELETE /certificates/{certID})

Details: None.

404

NOT_FOUND

None

Message: Describes the missing resource; for example KeyPair with id: <keyID> does not exist for environment: <envID> for a key, or Certificate not found for id: <certID> and environmentId: <envID> for a certificate

When and details

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

Details: None.

500

UNEXPECTED_ERROR

None

Message: Describes the processing failure; for example Environment key was not updated for a key update that could not be persisted

When and details

When: The service fails to process the request (for example, a database or cryptographic error)

Details: None.