--- title: Key Rotation Policies description: The certificate management service supports automatically rotating key pairs for OIDC-based applications. Key rotation is the process of generating a new version of a cryptographic key for data encryption and then replacing the old key. Regular key rotation reduces risk by limiting the amount of data protected by a single key. component: pingone-api page_id: pingone-api:platform:certificate-management/key-rotation-policies canonical_url: https://developer.pingidentity.com/pingone-api/platform/certificate-management/key-rotation-policies.html section_ids: key-rotation-policy-data-model: Key Rotation Policy data model signing-request-data-model: Signing Request data model signing-response-data-model: Signing Response data model response-codes: Response codes --- # Key Rotation Policies The certificate management service supports automatically rotating key pairs for OIDC-based applications. Key rotation is the process of generating a new version of a cryptographic key for data encryption and then replacing the old key. Regular key rotation reduces risk by limiting the amount of data protected by a single key. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Beginning March 2, 2027, PingOne will only use signing keys from KRPs to sign ID tokens and access tokens, regardless of whether the audience for the access token is PingOne APIs or custom resources. Any OIDC-based applications not using the KRP will automatically update to use the default KRP on this date. | 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, by default 90 days. 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}}/v1/environments/{{envID}}/keyRotationPolicies` operation. PingOne allows up to five KRPs per environment. 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. |