Entity Deliveries

Entity admins can deliver a document encryption key directly to a specific member without a grant. The recipient decides whether to accept.

The application server stores encrypted delivery payloads and opaque tokens. Persistent storage does not expose the document key, plaintext document relationship, or plaintext recipient identity.

Deliveries vs. Grants

Use a grant when the document holder wants a consent-based claim/accept flow with discovery through view tags.

Use an entity delivery when an entity admin needs to push document access directly to a known member of the organization. The recipient still accepts or denies the delivery, but discovery is scoped to entity membership rather than public grant tags.

Prerequisites

Before starting:

• An active session with admin role in the target entity (see Entity Onboarding).
• The target member must have completed membership claim and registered delivery public keys.
• The document encryption key the admin wants to deliver.

Endpoint Sequence

• POST /v1/issuances/reservations
• GET /v1/entities/{id}/memberships
• POST /v1/issuances
• GET /v1/issuances
• PATCH /v1/issuances/{delivery_token}
• GET /v1/issuances/received

Use the API Reference for exact request fields, response bodies, and errors.

Step 0 — Reserve A Delivery Slot

Before encrypting the payload, the admin reserves a delivery slot. Literal returns a delivery ID and commitment nonce.

The client includes the commitment nonce in AEAD authentication data when encrypting the delivery payload. This binds the ciphertext to the reserved slot and prevents replay into a different delivery.

Endpoint: POST /v1/issuances/reservations

If the reservation expires before the delivery is submitted, reserve again. The new commitment nonce must be incorporated into a fresh encryption.

Step 1 — Create The Delivery

The admin client:

1. Fetches the recipient’s delivery public keys from the entity membership list.
2. Encrypts or wraps the document key for the recipient.
3. Computes hash-lock commitments for the recipient key material.
4. Includes the reservation commitment in AEAD context.
5. Submits the encrypted delivery payload.

Endpoints:

• GET /v1/entities/{id}/memberships
• POST /v1/issuances

Only members who have completed membership claim have delivery keys; members without delivery keys cannot receive deliveries. Only entity admins can create deliveries.

Step 2 — Discover Pending Deliveries

Recipients discover pending deliveries within an entity context. Unlike grants, deliveries do not use public view-tag scanning. Literal matches pending deliveries against the recipient’s stored delivery key commitment and returns deliveries addressed to that member.

Endpoint: GET /v1/issuances

Step 3 — Accept Or Deny

To accept, the recipient decrypts the payload locally, re-wraps the document key under their personal master key, and submits proof of possession for the expected delivery key.

Literal checks:

1. The recipient key matches the committed recipient hash.
2. The recipient proof is valid.
3. The admin capability is valid.

If accepted, the delivery stores a wrapped document key for the recipient. If denied, no document key is stored for later use. If any check fails, the delivery remains pending.

Denial does not require decryption proof. The state transition is recorded without revealing whether the recipient decrypted the payload.

Endpoint: PATCH /v1/issuances/{delivery_token}

Step 4 — List Received Deliveries

Accepted deliveries can be listed later. Each accepted delivery includes the wrapped document key and opaque document/entity tokens needed for follow-up operations.

Endpoint: GET /v1/issuances/received

Delivery States

Deliveries move through four states: pending, accepted, denied, and expired. Pending deliveries wait for recipient action. Accepted deliveries expose the recipient’s wrapped document key. Denied and expired deliveries are terminal.

Expiry is enforced by a server-side alarm registered at create time, not by a database sweep.

Visibility Model

The application server can see encrypted payloads, opaque entity and document tokens, key commitments, delivery status, timestamps, and expiry.

It does not receive the document encryption key, decrypted payload, plaintext document metadata, or plaintext relationship fields in persistent storage.

Troubleshooting

• If a member has no delivery keys, confirm they completed membership claim.
• If delivery creation fails, confirm the caller has admin role.
• If acceptance fails, confirm the recipient is using the expected delivery key material.
• If a delivery expired, create a new delivery.
• If accepted delivery content cannot be decrypted, confirm the wrapped key was re-wrapped under the recipient’s current personal key material.

See Error Handling and the API Reference for status-specific responses.

Related Resources

• Entities & Memberships — entity roles, membership claim, and delivery key population.
• Entity Onboarding — creating entities, adding members, and fetching the member list.
• Creating And Claiming Grants — alternative sharing mechanism using view tags and consent-based claims.
• Key Hierarchy — how entity, member, and document keys are structured.

Last updated on