Skip to main content
POST
Rotate KMS key

Authorizations

X-Qanapi-Authorization
string
header
required

A machine credential, qk_ followed by its secret. The first twelve characters are an indexed prefix; the rest is compared in constant time against a stored SHA-256 hash. A key reaches only the configurations it is linked to.

It may also be sent as Authorization: Bearer qk_..., which is recognised by the prefix.

Path Parameters

uuid
string<uuid>
required

The key's key_id.

Body

application/json
export_on_create
boolean
default:false
wrap_with_key_id
string<uuid>

Response

The replacement key.

key_id
string<uuid>
required
type
enum<string>
required
Available options:
AES,
RSA
algorithm
string
required

Named as the v3 API this service replaces names it: the key length without the cipher mode.

Examples:

"AES-256"

"RSA-2048"

state
enum<string>
required
Available options:
active,
revoked
created_at
string<date-time>
required
private_material_retrievable
boolean
required

Whether the private half may ever leave this service. Fixed at creation: it can be withdrawn later but never granted, because the guarantee made when the key was generated has to keep holding.

usage_mask
enum<string>[]
required
Available options:
encrypt,
decrypt,
sign,
verify
updated_at
string<date-time>
required
name
string | null
external_id
string | null

A caller's own identifier, for reconciling against another system.

cipher_mode
enum<string>

Absent for RSA. This service tracks the mode per key and the v3 API does not, so it is reported here rather than folded into algorithm.

Available options:
gcm,
cbc
classification_id
string<uuid>
revoke_reason
string
rotated_from
string<uuid>

The key this one replaced, when it came from a rotation.

export_window_expires_at
string<date-time> | null

After this, export is refused even for an exportable key. Present only on exportable keys.

export_count
integer

How many times the private half has been exported.

public_key_pem
string

RSA keys only.

private_key_material
object

Present only in the response to an export, or to a create with export_on_create. Never returned by a plain fetch.