Skip to main content
PATCH
Update a KMS key

Authorizations

X-Qanapi-Authorization
string
header
required

A machine credential, qk_ followed by its secret. Only a hash of the secret is stored, so a key is displayed exactly once, when it is created or rotated. 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

Every field is optional, and one that is absent is left alone.

name
string
external_id
string
usage_mask
enum<string>[]
Available options:
encrypt,
decrypt,
sign,
verify
private_material_retrievable
boolean

May be set to false, never to true.

export_window_expires_at
string<date-time>

Response

Updated.

The compact form returned by the list endpoint.

key_id
string<uuid>
required

How every other KMS endpoint names this key.

name
string | null
required
external_id
string | null
required

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

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

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

What the key may be used for. Defaults to ["encrypt", "decrypt"] when a key is created without one.

Available options:
encrypt,
decrypt,
sign,
verify
updated_at
string<date-time>
required
cipher_mode
enum<string>

The AES mode. Absent for an RSA key, which has none.

Available options:
gcm,
cbc
classification_id
string<uuid>

Present when the key carries a classification. Decrypting through it then requires the matching clearance.

revoke_reason
string

Present only on a revoked key, and only when one was given.

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. Present only on exportable keys.

public_key_pem
string

RSA keys only, and always safe to hand out.

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.