Key Operations Widening Forbidden
URI: https://docs.ankatech.co/errors/key-ops-widening-forbidden
HTTP Status: 422 Unprocessable Entity
When you see this
A key rotation supplied an explicit key_ops set that adds an operation the current PRIMARY material does not permit, and the tenant's rotation policy sets requireOpsSubset to true. Under that policy the new key operations must be a subset of the current ones, so a rotation may only keep the operation set exactly as it is.
requireOpsSubset is an opt-in restriction. It is false in every seeded rotation policy template and in a new environment, and an administrator sets it on a custom rotation policy to turn it on. While it is false, a rotation may add operations within the key's purpose and this refusal never occurs.
The gate runs after the purpose gate and the narrowing gate, and before any new key material is generated, so a refused rotation leaves the key exactly as it was. A key_ops set that both drops and adds operations is refused as narrowing first.
Common Causes
- Rotating a key that permits only
verifywhile supplyingkey_opsof["sign", "verify"]. - Rotating a key that permits only
decryptwhile supplying["encrypt", "decrypt"]. - Copying a
key_opsarray from a different key that happens to be wider than the current material's.
Response Example
{
"type": "https://docs.ankatech.co/errors/key-ops-widening-forbidden",
"title": "Key Operations Widening Forbidden",
"status": 422,
"detail": "Rotation target would add key operations [encrypt] the current key material does not permit, and the rotation policy requires the new key operations to be a subset of the current ones.",
"instance": "/api/v3/admin/tenants/7c9e6679-7425-40de-944b-e07fc1f90ae7/keys/my-mlkem-key/rotations",
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": 1730000000,
"extensions": {
"errorCode": "KEY_OPS_WIDENING_FORBIDDEN"
}
}
Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.
The detail names only the added operations. It never carries key material, the kid, a UUID or a tenant identifier; the kid you supplied is echoed in instance.
The example above shows the Core API shape — the Core API is where this refusal originates, and it carries the correlation identifier as the top-level correlationId. The Admin API relays the same refusal on its tenant-scoped rotation route (POST /api/v3/admin/tenants/{tenantId}/keys/{kid}/rotate), so on that path instance is the Admin API route and the correlation identifier is extensions.requestId — see Where extension members live.
Branch on type, not on errorCode
extensions.errorCode is emitted by the Core API and is convenient for a direct integration, but it does not survive the Admin API relay: the relay's problem view is a closed four-member record (type, title, status, detail), so extension members are dropped end to end.
type is the identifier to dispatch on. RFC 9457 §3.1.1 makes it the primary identifier of a problem, this type is a dedicated slug rather than a shared one, and it is relayed unchanged — so a consumer branching on type gets the same discrimination on both the direct and the relayed path, and never has to parse detail.
if ("https://docs.ankatech.co/errors/key-ops-widening-forbidden"
.equals(problemDetails.getType().toString())) {
// resubmit with the current key_ops, or omit key_ops
}
How to Resolve
- Read the current PRIMARY material's
key_ops(GET /api/v3/key-management/keys/{kid}/metadata). - Resubmit the rotation with exactly that set, in any order.
- Or simply omit
key_ops. A rotation that omits it inherits the current operations, which can never add one.
Adding an operation under a subset-only policy
If the key genuinely needs an operation it does not hold, either create a key with the wider operation set, or have an administrator rotate it under a rotation policy that sets requireOpsSubset to false. Such a widening may still wait on the tenant's key weakening update quorum where its policy gates one.
For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.