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 server stores the encrypted payload but cannot read the key, identify the parties, or determine which document is involved.

Overview

Step 0 — Reserve A Delivery Slot (Admin)

Before encrypting, reserve a delivery slot with the server. This gives you a server-authoritative delivery_id and a commitment_nonce — a 16-byte random value the server generates to bind the encrypted payload to this specific slot.

Why Reservation?

Including the commitment nonce in the AEAD authentication data means the ciphertext is cryptographically bound to this delivery slot. Any attempt to replay the encrypted payload on a different delivery ID fails immediately — the integrity tag will not verify.

Reserve A Slot

curl -X POST https://api.kyndex.co/v1/issuances/reservations \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_token": "<base64-32-bytes>",
    "doc_token": "<base64-32-bytes>"
  }'

Response (201 Created):

{
  "delivery_id": "11111111-2222-3333-4444-555555555555",
  "commitment_nonce": "<base64-16-bytes>"
}

Step 1 — Create The Delivery (Admin)

With the reservation in hand, encrypt the DEK for the recipient and submit it. Only entity admins can create deliveries.

Fetch Recipient Delivery Keys

Before encrypting, fetch the target member's delivery public keys from the member list:

curl https://api.kyndex.co/v1/entities/{id}/memberships \
  -H 'Authorization: Bearer <access_token>'

Each member record in the response includes:

Only members who have completed the membership claim step have delivery keys. Members without them are excluded from the list.

Build The Encrypted Payload

Your device performs these steps before submitting:

1. Derive your admin DSA keypair — derive a per-entity admin delivery keypair from your blind index key and entity ID.
2. Compute hash-lock commitments — SHA-256(recipient_mlkem_ek) and SHA-256(recipient_dsa_vk). The server uses these at acceptance time to verify the correct recipient is responding.
3. Encrypt the DEK — hybrid KEM (ML-KEM-1024 + X25519) encapsulates a shared secret using the recipient's delivery_mlkem_ek. The DEK, capability payload, and admin signature are encrypted as the payload with the commitment nonce, tokens, and aad_ts in the AEAD authentication data.
4. Record aad_ts — capture your current Unix timestamp (seconds). This value must be passed verbatim in the request and is included in the AEAD authentication data.

Submit The Delivery

curl -X POST https://api.kyndex.co/v1/issuances \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_token": "<base64-32-bytes>",
    "doc_token": "<base64-32-bytes>",
    "aad_ts": 1743724800,
    "admin_delivery_vk": "<base64-1984-bytes>",
    "ephemeral_pubkey": "<base64-1600-bytes>",
    "encrypted_payload": "<base64>",
    "pending_recipient_ek_hash": "<base64-32-bytes>",
    "pending_recipient_dsa_hash": "<base64-32-bytes>",
    "delivery_id": "11111111-2222-3333-4444-555555555555"
  }'

Response (201 Created):

{
  "delivery_token": "<base64-32-bytes>",
  "status": "pending",
  "expires_at": "2026-04-15T00:00:00.000Z",
  "created_at": "2026-04-08T00:00:00.000Z"
}

A Location header pointing to the new resource is also returned.

Step 2 — Discover Pending Deliveries (Recipient)

Recipients query for deliveries addressed to their encryption key. Unlike grant discovery, there is no tag scanning or false-positive filtering — the server resolves your membership, hashes your stored delivery_mlkem_ek, and returns only deliveries addressed to that exact key.

curl 'https://api.kyndex.co/v1/issuances?entity_token=<base64-32-bytes>' \
  -H 'Authorization: Bearer <access_token>'

Response (200 OK):

{
  "count": 1,
  "deliveries": [
    {
      "delivery_token": "<base64-32-bytes>",
      "entity_token": "<base64-32-bytes>",
      "doc_token": "<base64-32-bytes>",
      "aad_ts": 1743724800,
      "ephemeral_pubkey": "<base64-1600-bytes>",
      "encrypted_payload": "<base64>",
      "commitment_nonce": "<base64-16-bytes>"
    }
  ]
}

To decrypt: use your ML-KEM private key and the ephemeral_pubkey KEM ciphertext to recover the shared secret, then use the shared secret (combined with the X25519 component) to decrypt encrypted_payload. The decrypted payload contains the DEK wrapped for your personal master key, the capability payload, and the admin's signature over it.

Step 3 — Accept Or Deny (Recipient)

Once you have decrypted the payload, you decide whether to accept the delivery. Both transitions use the same PATCH endpoint — the status field in the request body determines which path is taken.

Accept The Delivery

Accepting requires re-wrapping the DEK under your personal master key and providing proof-of-possession:

1. Unwrap the DEK — decrypt the DEK from the payload using your personal key.
2. Re-wrap under your UMK — wrap the DEK with your personal master key (UMK) to produce wrapped_dek_umk. This is the form stored for your later use.
3. Sign the accept message — sign "kyndex-delivery-accept-v1" || delivery_token(32 bytes) || owner_token(32 bytes) with your hybrid DSA private key (ML-DSA-65 + Ed25519).

curl -X PATCH https://api.kyndex.co/v1/issuances/{delivery_token} \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "accepted",
    "doc_token": "<base64-32-bytes>",
    "entity_token": "<base64-32-bytes>",
    "wrapped_dek_umk": "<base64>",
    "capability_payload": "<base64>",
    "admin_signature": "<base64-3373-bytes>",
    "recipient_dsa_vk": "<base64-1984-bytes>",
    "recipient_signature": "<base64-3373-bytes>"
  }'

Response (200 OK):

{
  "status": "accepted"
}

The server runs three checks before transitioning the delivery:

1. Hash-lock — SHA-256(recipient_dsa_vk) must match pending_recipient_dsa_hash stored at creation. Prevents key substitution.
2. Proof-of-possession — your recipient_signature must verify over "kyndex-delivery-accept-v1" || delivery_token || owner_token using recipient_dsa_vk. Proves you hold the private key.
3. Admin capability — admin_signature must verify over capability_payload using the admin_delivery_vk stored at creation. Proves the admin authorised this specific delivery.

All three must pass. If any fails, the delivery remains pending.

Deny The Delivery

Denial requires no cryptographic material — just the status discriminant:

curl -X PATCH https://api.kyndex.co/v1/issuances/{delivery_token} \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "denied"
  }'

Response (200 OK):

{
  "status": "denied"
}

Denying does not reveal whether the recipient decrypted the payload — the server only records the state transition.

Step 4 — List Received Deliveries (Recipient)

Once accepted, deliveries appear in your received list with the wrapped DEK ready for local use:

curl https://api.kyndex.co/v1/issuances/received \
  -H 'Authorization: Bearer <access_token>'

Response (200 OK):

{
  "deliveries": [
    {
      "delivery_token": "<base64-32-bytes>",
      "doc_token": "<base64-32-bytes>",
      "entity_token": "<base64-32-bytes>",
      "wrapped_dek_umk": "<base64>",
      "accepted_at": "2026-04-08T12:00:00.000Z"
    }
  ]
}

Delivery Status Reference

Expiry is enforced by a server-side alarm registered at create time. The delivery defaults to 7 days unless an expires_at was specified at creation.

API Endpoint Summary

All endpoints require an unlocked session. There are no unauthenticated delivery endpoints.

Error Handling

All errors follow the RFC 7807 Problem Details format.

What The Server Sees (And Doesn't)

Related Resources

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