Encryption — MDDB API

At-rest encryption posture (2.9.16+) #

GET /v1/encryption/status

Primary keyID, configured previous keyIDs, and per-collection counts of how each document is sealed (primary / legacy / plaintext / unknown).

Authorization: BearerAuth or APIKeyAuth

Responses #

Status	Description	Body
200	Encryption status	object (application/json)
401	Missing or invalid token
403	Not an admin

Start a re-encryption job (2.9.16+) #

POST /v1/encryption/rotate

Walks every encrypted entry sealed under a non-primary key and re-seals it with the current MDDB_ENCRYPTION_KEY. Plaintext entries and entries already under the primary keyID are skipped. Single-flight: calling rotate while a job is running returns the existing job's ID.

Authorization: BearerAuth or APIKeyAuth

Request body #

Content type application/json: object

Property	Type	Description
collection	string	Optional scope; empty = all collections

{
  "collection": "string"
}

Responses #

Status	Description	Body
200	Rotation job descriptor	RotationJob (application/json)
400	Encryption not configured
401	Missing or invalid token
403	Read-only mode or not an admin

List rotation jobs (2.9.16+) #

GET /v1/encryption/jobs

Authorization: BearerAuth or APIKeyAuth

Responses #

Status	Description	Body
200	Jobs list (newest first)	object (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
404	At-rest encryption is not configured	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Get a single key-rotation job #

GET /v1/encryption/jobs/{id}

Returns the status and progress of one encryption rotation job by ID.

Authorization: BearerAuth or APIKeyAuth or none

Parameters #

Name	In	Type	Description
id (required)	path	string	Rotation job ID

Responses #

Status	Description	Body
200	Rotation job status	object (application/json)
404	Job not found	ErrorResponse (application/json)