Jump to

Vault Keys

Vault keys protect your organization's encryption key. There are two types:

Type	Purpose
`primary`	The main vault key used for day-to-day access
`recovery`	Backup keys generated during vault initialization, used to regain access if the primary key is lost

The server stores wrapped (encrypted) copies of the organization encryption key — one per vault key. It never has access to the unwrapped encryption key or the vault keys themselves.

List vault keys GET

GET /vault/keys

List all vault keys (metadata only — no wrapped key material). Optionally filter by key type.

Query parameters

Parameter	Type	Description
`type`	string	Filter by type: `primary` or `recovery`

Response (200)

JSON

Code examples

Replace primary key PUT

PUT /vault/keys/primary

Replace the primary vault key. You must prove possession of either the current primary key or a recovery code. When using a recovery code, that recovery key is consumed (invalidated) after the replacement.

Request body

Field	Type	Required	Description
`id`	UUID	Yes	New vault key ID (client-generated)
`wrapped_org_encryption_key`	string	Yes	Org encryption key wrapped with the new vault key (base64)
`auth_hash`	string	Yes	SHA-256 hash of the new vault key
`current_auth_hash`	string	One of	SHA-256 hash of the current primary key (proves current key possession)
`recovery_auth_hash`	string	One of	SHA-256 hash of a recovery code (consumes the recovery key)

Exactly one of current_auth_hash or recovery_auth_hash must be provided.

Request example (normal rotation)

JSON

Response (200)

JSON

Error responses

Status	Description
400	Must provide exactly one of `current_auth_hash` or `recovery_auth_hash`
403	Invalid auth hash — key verification failed
404	Vault not found or recovery key not found

Code examples

Revoke vault key DELETE

DELETE /vault/keys/{auth_hash}

Revoke a vault key by its auth hash. The key is invalidated and can no longer be used to unlock the vault. This operation is refused if the key is the last active key.

Path parameters

Parameter	Type	Description
`auth_hash`	string	SHA-256 hash of the vault key to revoke

Error responses

Status	Description
409	Cannot revoke the last active primary vault key
404	Vault key not found

Code examples

Vault key object

Field	Type	Description
`id`	UUID	Unique vault key identifier
`key_type`	string	Key type: `primary` or `recovery`
`created_by`	string	User ID that created this key
`status`	string	Lifecycle status: `active`, `invalidated`
`invalidated_at`	string \| null	When the key was revoked (ISO 8601), or `null` if active
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)