Get a container writer projection | API reference

Description

Returns everything a client needs to read and write under a container: the signed manifests on its authorizing container path, each path level's container KEK wraps and keyring, and the key targets. Requires current read access; write authority is checked again when a write commits. A 202 asks the client to retry the identical request after the server prepares policy history, and the x-known-manifests header lets a client skip manifests it already holds.

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
`x-known-manifests`	header	string	optional at most 3,215 characters Comma-separated typed digests the device holds verified: m:<manifest hash> for an access-manifest bundle, k:<level digest> for a container KEK level; at most 48, unique

Responses

200 OK

application/jsonContainerWriterProjectionWireResponse

A container writer projection: the signed manifests on its path and the KEK levels a client needs to read and write under it. Every manifest is carried once in bundles and cited by hash.

7 fields

bundlesmap of string to AccessManifestBundleWireResponserequired
Signed manifest bundles keyed by manifest hash.
omittedBundleslist of stringrequired
- each item: not empty
Cited hashes left out because the request said the client holds them.
containerIdstringrequired
containerKekslist of one of: CitedContainerKekLevel, objectrequired
One KEK level for each manifest in path.
1. CitedContainerKekLevel
2. object
  12 fields
  - accessManifestHashstringrequired
    - not empty
  - containerIdstringrequired
  - containerKeyEpochintegerrequired
    - greater than 0
  - containerKeyEpochIdstringrequired
    - not empty
  - containerManifestHistorylist of stringrequired
    - each item: not empty
  - keyEpochobject with any fieldsrequired
  - keyEpochHashstringrequired
    - not empty
  - keyringContainerKekKeyringWireRecordrequirednullable
  - keyTargetHashstringrequired
    - not empty
  - parentContainerKeyEpochIdstringrequirednullable
  - recipientTargetslist of object with any fieldsrequired
    - at least 1 item
  - wrapslist of object with any fieldsrequired
    - at least 1 item
  Other fields are allowed.
organizationIdstringrequired
pathlist of stringrequired
- at least 1 item
- each item: not empty
Manifest hashes from the organization's root to this container.
policyEvidenceProjectionPolicyEvidenceResponserequired
Public principal policy history the cited manifests depend on.

Other fields are allowed.

202 Accepted

application/jsonPrincipalHistoryPreparationResponse

A 202: the operation rolled back while the server prepares principal history. Retry the identical request.

3 fields

codestringrequired
- always principal_history_preparation_pending
committedbooleanrequired
- always false
progressTokenstringrequired
- exactly 64 characters
- lowercase hexadecimal
Changes when preparation advances; clients stop after three identical tokens in a row.

Other responses

Status	Meaning	Body
400	Bad Request	`application/json`ErrorResponse
401	Unauthorized	`application/json`SessionFailureResponse
403	Forbidden	`application/json`ErrorResponse
404	Not Found	`application/json`ContainerNotFoundErrorResponse
409	Conflict	`application/json`ContainerWriterProjectionErrorResponse
500	Internal Server Error	`application/json`ErrorResponse
503	Service Unavailable	`application/json`ErrorResponse

Additional rules

The server also enforces these rules, which the schema above cannot express.

containerKeks must contain exactly one entry for every manifest in path.
A container response keyring is null exactly for container key epoch 1.
Every cited manifest hash names one bundles entry, every bundles key equals its bundle's manifestHash, and every bundle is cited.
X-known-manifests must list at most 48 unique typed digests, each m: or k: followed by a lowercase SHA-256 hex digest.