Skip to content

Schedule automatic rotation for one key

Make one key rotate by itself: on an interval, when its uses reach its soft usage limit, when its usage limit is exhausted, or whichever of these comes first.

Who can do it

A tenant administrator, a tenant key manager, or a platform super administrator working inside the tenant. Anyone who may read rotation schedules sees the key's Automatic rotation section; only a person who may change rotation schedules gets its switches and Edit. Everyone else reads each setting as enabled or disabled.

Before you start

  • A usage trigger needs the matching limit on the key: At the soft usage limit needs a soft usage limit, and When the usage limit is exhausted needs a maximum usage limit. Set them first by editing the key's metadata if they are missing.
  • An interval can come from the key itself, or be inherited from the tenant default or the deployment default. An interval below the deployment's minimum is refused before anything is sent.
  • The key must be in a state that can be rotated; otherwise the section says the key cannot be rotated in its current state.

Steps

  1. Open Key Inventory and select View Details on the key.
  2. On the Details tab, find Automatic rotation.
  3. Turn on Rotate this key automatically.
    • With an interval or a usage trigger already in place, rotation takes effect at once.
    • With none, the section opens the triggers and asks you to choose one. Nothing is saved until you do.
  4. Under When to rotate, choose the triggers:
    • To give the key an interval of its own, select Edit beside the interval, check Use an interval of its own for this key, enter the Amount and choose the Unit, then select Save. Unchecked, the key follows the inherited interval, and the editor says which one.
    • Turn on At the soft usage limit, When the usage limit is exhausted, or both. Each switch saves as soon as you change it.
  5. To stop automatic rotation, turn off Rotate this key automatically and confirm with Turn off. The triggers keep their settings, shown paused, until you turn it on again. Turning off the last trigger also turns automatic rotation off, and asks for the same confirmation.

What you see when it worked

The console says Rotation schedule saved, and the sentence under the switch states what will rotate the key, for example that it rotates every interval or at the soft usage limit, whichever comes first. The section shows the Effective interval, the Next rotation and the Tolerance: the window after the due instant within which the scheduler starts the rotation, so that keys due together do not rotate at once. A rotation never starts before the due instant.

The Next rotation row in the key's details, and the Next rotation column of Key Inventory, show the new date in your display time zone. Each automatic rotation appears on the Rotation schedule tab with its state and result, and on the Lineage tab with the cause Scheduled, Usage threshold or Usage limit reached. Every rotation, automatic or not, restarts the count and the interval from the new version.

If it fails

What you see Cause What to do
The shortest interval this deployment admits is the minimum shown The interval is below the deployment's minimum Choose a longer interval
Current value: an interval in a unit this deployment no longer admits The stored interval uses hours or minutes the deployment no longer allows Choose days, months or years before saving
A usage option cannot be turned on The key has no soft usage limit, or no maximum usage limit Set the limit on the key, then turn the option on
Save stays disabled with a note that this interval is the only rotation trigger Removing the key's own interval would leave nothing to rotate on, and the server does not say whether an inherited interval would take its place Turn on another trigger first
The interval is shortened, with a note The deployment maximum, or the maximum cryptoperiod a compliance pack states for that key class, is shorter than the interval you chose Nothing; the key rotates on the shortened interval
A change is refused The server refused the schedule; the reason is shown next to the control you used Correct what the reason names and try again

Without the console

Surface How
Key management CLI ankasecure-km rotation replace-schedule --kid <id> --body-file <json>; read it with ankasecure-km rotation schedule --kid <id>
Admin SDK RotationOperations.replaceSchedule(String kid, KeyRotationScheduleRequest request)
API PUT /api/v3/admin/tenants/{tenantId}/keys/{kid}/rotation-schedule (operation replaceKeyRotationSchedule)
  • Key Inventory: what the screen shows and every decision you make on it.