POST/containers/{containerId}/rekey
Operation containers.rekey
Description
Rotates a container's KEK to a new epoch without changing grants, carrying the predecessor bridge and the re-sealed container KEK keyring. Requires write access. Stale cited heads return 409, and epochs above 65536 are refused.
Authentication
Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.
Parameters
| Name | In | Type | Details |
|---|---|---|---|
containerId | path | string | required |
Request body
application/jsonContainerRotationRequest
A rekey, revoke, or move, which rotates the container KEK, plus the descendant rekeys that must commit with it.
17 fields
bodyany JSON valuerequired- at most 4,096 items
- at most 100 items
eventobject with any fieldsrequiredexpectedManifestHashstringrequired- not empty
keyEpochobject with any fieldsrequiredmanifestobject with any fieldsrequired- at most 100 items
parentKekRefobjectoptionalnullable3 fields
containerIdstringrequired- not empty
containerKeyEpochIdstringrequired- not empty
keyEpochHashstringrequired- exactly 64 characters
- lowercase hexadecimal
Other fields are allowed.
predecessorBridgeobject with any fieldsrequirednullable- at most 100 items
userRecipientKeyslist of object with any fieldsoptionalwrapslist of object with any fieldsrequired- at most 64 items
Descendant rekeys, parent first; they commit with the rotation or not at all.
Other fields are allowed.
Responses
200 OK
application/jsonContainerRotationResponse
Acknowledges a rotation, plus one acknowledgement per carried descendant rekey in request order.
10 fields
containerIdstringrequiredcreatedAtstringrequiredeventHashstringrequired- not empty
manifestHeadobjectrequired2 fields
epochnumberrequiredmanifestHashstringrequired
Other fields are allowed.
organizationIdstringrequiredparentIdstringrequirednullablesystemSlotstringoptionalnullable- pattern
^sys_v1_[A-Za-z0-9_-]{43}$
- pattern
updatedAtstringrequiredcontainerKekobjectrequired6 fields
containerKeyEpochintegerrequired- greater than 0
containerKeyEpochIdstringrequired- not empty
keyEpochHashstringrequired- not empty
keyringHashstringrequirednullable- not empty
keyTargetHashstringrequired- not empty
parentContainerKeyEpochIdstringrequirednullable
Other fields are allowed.
Other fields are allowed.
Other responses
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad Request |
|
| 401 | Unauthorized |
|
| 402 | Payment Required |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 503 | Service Unavailable |
|
Additional rules
The server also enforces these rules, which the schema above cannot express.
A container response keyring is null exactly for container key epoch 1.