Skip to content

Revoke or destroy one version of a key

Act on one material version of a key without touching the version in current use: revoke a retired version, request its destruction, or cancel a scheduled destruction of it.

Who can do it

A tenant administrator, a tenant key manager, or a platform super administrator working inside the tenant. Reading the versions, revoking one, requesting a destruction and cancelling one are separate permissions; the Lineage tab and each action appear only with the matching permission. The approval of a destruction is given by a person other than the requester.

Before you start

  • A version can be revoked while it is retired or about to become current. The version in current use cannot be revoked on its own: rotate the key, or revoke the whole key.
  • The cause of a version's revocation decides what it may still do afterwards: decrypt or verify historical data, and re-encryption off it. A security compromise stops them; any other cause leaves them to your tenant's lifecycle policy.
  • A destruction request always waits for another person's approval. Once approved, the version is destroyed when its cooling-off period ends, 7 to 365 days after the approval.
  • When a version is the key's last one not already being destroyed, requesting its destruction is the destruction of the whole key. That needs an archived key and the permission to request key destructions, and the console says so before you confirm.

Steps

  1. Open Key Inventory, select View Details on the key, and open the Lineage tab.
  2. On the version's row, open Material actions. It offers only the actions that apply to that version.

To revoke the version:

  1. Select Revoke.
  2. Choose the Cause and write the Reason. Both are required; the reason is the sentence an auditor reads.
  3. Select Revoke material.

To request the version's destruction:

  1. Select Mark for destruction.
  2. Optionally set the Cooling-off period (days), then write the Reason.
  3. Select Mark for destruction. On the key's last version the dialog is titled Request to destroy the whole key, and the button is Request destruction of the key.

To cancel a scheduled destruction of the version:

  1. Select Cancel destruction on a version pending destruction.
  2. Confirm with Cancel destruction.

What you see when it worked

  • Revoke: the console says the version is revoked, and the Lineage tab shows it revoked with its cause. Only that version changes.
  • Destruction request: the dialog shows Waiting for approval with a link to the quorum request, and nothing changes until another person approves it. Once approved, the version reads pending destruction, and the platform destroys it when the cooling-off period ends. Destroying the key's last version destroys the key and ends every authorization that names it, as destroying the key does.
  • Cancellation: the console says the destruction of that version is cancelled. The version keeps its key material and returns to the state it held before. If the version was part of a destruction of the whole key, the whole key destruction is cancelled.

Each act is recorded in the audit trail.

If it fails

What you see Cause What to do
Material actions is not shown on a version No action applies to that version, or you lack the permission Check the version's status
Revoking is refused as an invalid transition The version is the one in current use, or its status does not allow revocation Rotate the key first, or revoke the whole key
Enter a whole number of days from 7 to 365. The cooling-off period is outside its bounds Correct it, or leave it empty
Failed to mark material for destruction The server refused: for the key's last version, the key is not archived; a request for the same version is already waiting; or no approver other than you is eligible Read the reason shown, correct it and retry
Failed to cancel destruction The version is no longer pending destruction, or the destruction has already run Reopen the Lineage tab to see the version's status

Without the console

Surface How
Key management CLI ankasecure-km materials revoke --kid <id> --material-version <n> --cause <cause> --reason <text>; ankasecure-km destruction request-version --kid <id> --material-version <n> --reason <text> [--cooling-off-days <7..365>]; ankasecure-km destruction cancel-version --kid <id> --material-version <n>
Admin SDK MaterialOperations.revoke(String stableKid, int version, MaterialRevokeRequest request); DestructionOperations.requestVersion(String stableKid, int version, MaterialMarkForDestructionRequest request); DestructionOperations.cancelVersion(String stableKid, int version)
API POST /api/v3/admin/tenants/{tenantId}/keys/{stableKid}/materials/{version}/revoke (operation revokeKeyMaterialVersion); POST …/materials/{version}/mark-for-destruction (operation markKeyMaterialVersionForDestruction), answered 202 with the quorum request; POST …/materials/{version}/cancel-destruction (operation cancelKeyMaterialVersionDestruction)