PingOne Platform APIs

Key Rotation Policies

The certificate management service supports automatically rotating key pairs. Administrators can update certificates with minimal intervention, eliminating many common configuration errors.

Resources called key rotation policies (KRPs) are exported through the PingOne API by the Certificate Management service. KRPs manage a set of key pairs that are created and rotated on a scheduled basis. These key pairs are referred to as KrpKeys to distinguish them from existing key pair resources. The cryptographic details of KrpKeys are managed by a specification attached to the KRP. The specification includes settings such as algorithm, key length, validity duration period, and distinguished name (DN). This specification and the rotation schedule are mutable after creation. Generated KrpKeys are always self-signed with no extraordinary extensions.

When an environment is created, PingOne creates an initial KRP configuration object as the default KRP. You can can create additional KRPs using the POST {{apiPath}}/environments/{{envID}}/keyRotationPolicies operation. There is no UI to manage KRPs in the PingOne admin console. PingOne allows up to five KRPs per environment. You won’t be able to create a new KRP if the environment already has five KRPs. You cannot delete the default KRP for an environment. A DELETE operation won’t succeed if the environment has only one KRP.

At any given time, a KrpKey has one of three designations: PREVIOUS, CURRENT, or NEXT. When created, a KRP has two KrpKeys with designations CURRENT and NEXT, respectively. After a period of time defined by a KRP’s rotation schedule, a new KrpKey is created and designated as NEXT. The KrpKey previously designated as NEXT transitions to CURRENT, and the KrpKey previously designated as CURRENT transitions to PREVIOUS.

A KRP exports another operation to list all KrpKeys that it manages. This is a read-only operation that returns a JSON Web Key set (JWKS) formatted file containing all public keys associated with a KrpKey managed by a KRP. This allows downstream clients to cache any public keys for use during signature validation. This operation is public and does not require an authentication token.

Key Rotation Policy data model

Property Type Required? Mutable? Description

algorithm

String

Required

Mutable

The algorithm this KRP applies to generated KrpKeys. RSA is currently the only supported value.

currentKeyId

UUID

N/A

Read-only

The kid (key identifier) of the KrpKey designated as CURRENT.

default

Boolean

Optional

Mutable

When creating or updating a KRP, setting this value to true designates the new or updated KRP as the default. The prior KRP is then set to false. Any attempts to update the default KRP to false are ignored.

dn

String

Required

Mutable

The DN this KRP will apply to generated KrpKeys. Is applied as both issuerDN and subjectDN because generated KrpKeys are self-signed.

id

UUID

N/A

Read-only

Unique identifier of the KRP.

environment.id

UUID

N/A

Read-only

Unique identifier of the environment that the KRP belongs to.

keyLength

Integer

Required

Mutable

The number of bytes of a cryptographic key this KRP will apply to generated KrpKeys.

name

String

Required

Mutable

Human-readable name displayed in the admin console.

nextKeyId

UUID

N/A

Read-only

The kid (key identifier) of the KrpKey designated as NEXT.

rotatedAt

Date

N/A

Read-only

The last time this KRP was rotated.

rotationPeriod

Integer

Optional

Mutable

The number of days to elapse before this KRP rotates KrpKeys. The default value is 90 days. The minimum value is 30 days. The maximum value is 1 day less than the validityPeriod value.

signatureAlgorithm

String

Required

Mutable

The signature algorithm this KRP will apply to generated KrpKeys. SHA256withRSA is currently the only supported value.

usageType

String

Required

Mutable

How the KRP will be used, pertaining to what operations the KRP supports. The only valid value for initial release is SIGNING.

validityPeriod

Integer

Required

Mutable

Controls the expiration date of each KrpKey certificate that appears in the KRP’s JSON Web Key Set (JWKS). Certificates are valid starting when the KrpKey becomes CURRENT and ending after the value specified here. The minimum value is 31 (days), the maximum value is 36500 (days = 10 years). The default value is 365 days.

Signing Request data model

Property Type Required? Mutable? Description

document

String

Required

Mutable

Base64-encoded binary document to sign.

signatureAlgorithm

String

Optional

Mutable

If present, this value overrides the signatureAlgorithm setting of the CURRENT KrpKey. SHA256withRSA is currently the only supported value.

Signing Response data model

Property Type Required? Mutable? Description

key

Object

N/A

Read-only

KrpKey delegated to perform the sign operation. This KrpKey is always designated as CURRENT rotation state.

key.id

UUID

N/A

Read-only

Unique identifier of the KrpKey.

signature

String

N/A

Read-only

Base64-encoded signature (MAC) as the result of the signing operation.

signatureAlgorithm

String

N/A

Read-only

The signature algorithm used to perform the sign operation. SHA256withRSA is currently the only supported value.

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.

500

An unexpected error occurred.