Skip to content

Rotate or revoke a workload credential

Replace a workload's public key with a new one without interrupting it, or stop a key at once when it is in doubt.

Who can do it

A tenant administrator, or a platform super admin working inside the tenant on a private-cloud or on-premise deployment. On a SaaS deployment the platform refuses a platform administrator's changes to a tenant's workloads. The console shows Rotate and Revoke only to a person who holds the permission to manage workload credentials, and only on a workload that is not revoked.

Before you start

  • To rotate, get the new public key from whoever runs the workload, as a JWK. You never receive the private key.
  • Only an Active key can be rotated. A key that is Rotating out can still be revoked.
  • Rotating is refused during a support-access session.

Steps

  1. Open Administrative Workloads and select the workload's name.
  2. Open the Keys tab.
  3. To rotate a key:
    1. Select Rotate on its row.
    2. Paste the new key into Public key (JWK).
    3. Set Grace period (hours): how long the old key is still accepted, from 0 to 720. Left empty, it is 24. A grace period of 0 revokes the old key at once and refuses every token the workload holds.
    4. Optionally set Valid until for the new key.
    5. Select Rotate.
  4. To revoke a key:
    1. Select Revoke on its row.
    2. Type the key's Key ID to confirm, and enter a Reason. The reason is recorded in the audit trail.
    3. Select Revoke key.

What you see when it worked

After a rotation the console confirms "Key {kid} registered as the replacement.". The new key is Active and accepted at once; the old key is Rotating out and shows until when it is still accepted. Update the workload to sign with the new key before the grace period ends.

After a revocation the console confirms "Key revoked.". The key is Revoked: every assertion signed with it and every token the workload already holds is refused at once. The workload's other keys keep working. Both changes are recorded in the audit trail.

If it fails

What you see Cause What to do
"Only an ACTIVE credential can be rotated. This credential is already rotating out or revoked." The key you are rotating is not Active Rotate an active key, or register a new key instead
"This public key is already registered. Generate a new key pair and register its public key." The new key is already registered, on this or another workload Ask for a new key pair
"This key contains private key material, so it was cleared and not sent. Paste the public key only." The pasted JWK carries a private member Ask for the public key only
The grace period is refused It is outside 0 to 720 hours Enter a value in range, or leave it empty
"Does not match. Type it exactly as shown, including capitalization." The typed Key ID differs from the key's Type the key ID exactly as shown
Rotating is refused with "Refused by the subset rule:", followed by the scopes you do not hold You do not hold every scope the workload holds Ask an administrator who holds them
"The administrative workload is revoked, which is terminal. Register a new workload instead." The workload itself is revoked Nothing to rotate; create a new workload if you need one

Without the console

Surface How
API POST /api/v3/admin/tenants/{tenantId}/workloads/{workloadId}/credentials/{kid}/rotate (operation rotateTenantWorkloadCredential)
API POST /api/v3/admin/tenants/{tenantId}/workloads/{workloadId}/credentials/{kid}/revoke (operation revokeTenantWorkloadCredential)