Creating And Claiming Grants

This guide walks through the grant workflow used when a document holder gives an organization or recipient time-limited access to an encrypted document.

For the conceptual model behind grants, see Grants & Sharing.

Overview

Endpoint sequence:

• POST /v1/grants/reservations
• GET /v1/users/{userId}/public-keys
• POST /v1/grants
• GET /v1/grants
• PUT /v1/grants/{id}/claim
• PATCH /v1/grants/{id}
• DELETE /v1/grants/{id}/claim
• POST /v1/documents/consumer-indexes

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

Step 0 — Reserve A Grant Slot

Before creating a grant, the document holder’s client reserves a grant slot. Literal returns a grant ID and commitment nonce.

The client includes the commitment nonce in the grant payload AAD before encryption. This binds the encrypted payload to the reserved grant context and prevents replay into a different grant slot.

Endpoint: POST /v1/grants/reservations

Step 1 — Create A Grant

The document holder’s client prepares an encrypted grant payload for the intended recipient.

The client:

1. Fetches the recipient’s public encryption keys.
2. Wraps or derives access to the document key for that recipient.
3. Computes the view tag used for grant discovery.
4. Encrypts the grant payload with the reservation commitment in AAD.
5. Sets an expiration time.
6. Optionally targets the grant to a recipient key commitment.

Endpoints:

• GET /v1/users/{userId}/public-keys
• POST /v1/grants

The grant is now stored in unclaimed status, waiting for the recipient to discover it. Literal stores the encrypted payload but cannot read it, identify the recipient, or determine which document is being shared.

Step 2 — Discover Grants

Recipients discover possible grants by querying view tags. View tags are intentionally ambiguous, so a query can return unrelated grants with the same tag.

The recipient attempts to decrypt each returned encrypted payload locally. Only a grant encrypted for that recipient opens successfully. Failed decryptions are discarded.

Endpoint: GET /v1/grants

Step 3 — Claim The Grant

After decrypting a grant payload, the recipient claims it with a per-grant claim token. The claim token is unique to that grant, so separate claims cannot be linked by a stable plaintext recipient identifier.

For targeted grants, the recipient also proves possession of the expected signing key before the claim is accepted.

Endpoint: PUT /v1/grants/{id}/claim

The encrypted payload is withheld from the recipient until the document holder accepts the claim — the recipient cannot access the document key until Step 4 completes.

Step 4 — Accept Or Deny The Claim

The document holder reviews the pending claim.

• Accept — the grant becomes active and the recipient can access the document key material.
• Deny — the grant enters a terminal denied state.
• Status check — the document holder can poll the grant status while waiting for a claim.

Endpoint: PATCH /v1/grants/{id}

Step 5 — Access The Document

With an active grant, the recipient can decrypt the document using the grant key material.

If the recipient wants the document to appear in personal search, the client must generate and submit personal blind index tokens for the document.

Endpoint: POST /v1/documents/consumer-indexes

These tokens are scoped to the grant claim token so they can be cleaned up when access ends.

Step 6 — Revoke Or Expire Access

Access can end in three ways:

• Document holder revoke — the document holder revokes the grant at any time. Endpoint: PATCH /v1/grants/{id}.
• Recipient self-revoke — the recipient voluntarily gives up access using only the per-grant claim token. Endpoint: DELETE /v1/grants/{id}/claim.
• Automatic expiry — when the grant’s time limit elapses, Literal automatically revokes it and cleans up associated tokens.

In all cases, the grant is marked revoked before cleanup begins, so access ends before token cleanup completes.

Example: Time-Limited KYC Access

A document holder needs to share a verified passport with a bank for 48 hours.

1. The bank provides the identifier or public key material needed to target the grant.
2. The document holder creates a 48-hour targeted grant.
3. The bank discovers and claims the grant.
4. The document holder accepts the claim.
5. The bank decrypts and verifies the document during the active window.
6. The grant expires automatically, or the document holder revokes it early.

Both parties stay in control:

• Document holder — chooses exactly which document to share, with whom, and for how long. Can revoke access at any point before expiry.
• Organization — verifies the document directly by decrypting the original. It does not depend on Literal to vouch for authenticity.
• Literal application layer — coordinates the exchange without receiving document plaintext or plaintext grant relationships.

List Grants For A Document

Document holders can list grants associated with a document using the document’s blind token. Literal verifies ownership through the authenticated session before returning grant summaries.

Endpoint: GET /v1/grants

Troubleshooting

• If a reservation expires, reserve a new slot and re-encrypt the grant payload with the new nonce.
• If discovery returns unrelated grants, discard any payloads that cannot be decrypted.
• If claim fails for a targeted grant, verify the recipient is using the expected signing key.
• If an operation fails because the grant is in the wrong state, fetch the current grant status before retrying.
• If access was revoked or expired, regenerate access through a new grant.

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

Related Resources

• Grants & Sharing — the conceptual model behind grants, view tags, and the zero-knowledge sharing lifecycle.
• Document Upload — how documents are encrypted and processed before being shared.
• Searching Over Encrypted Documents — generate personal search tokens after claiming a shared document.
• Blind Routing — how grant relationships are stored as opaque tokens.

Last updated on