Entity Onboarding

This guide walks through the organization setup workflow: creating an entity, adding members, claiming membership, and preparing organization-scoped document workflows.

For the conceptual model behind entities and memberships, see Entities & Memberships.

Prerequisites

Before starting, you need:

• An authenticated Literal account.
• An active access token.
• Admin credentials or privileges required to create an entity.
• Public key material for members you plan to add.

Endpoint sequence:

• POST /admin/entities
• POST /v1/entities/{id}/memberships
• PUT /v1/entities/{id}/memberships/{membershipId}/claim
• POST /v1/users/index-jobs
• GET /v1/entities
• GET /v1/entities/{id}/memberships
• DELETE /v1/entities/{id}/memberships/{membershipId}

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

Personal And Organization Scope

Literal distinguishes between two scopes of operation:

• Personal scope — a document holder manages personal documents and keys.
• Organization scope — members operate within an organization, where document access, metadata, and search are scoped to the entity.

A single user can operate in both scopes simultaneously.

Step 1 — Create An Organization

Creating an entity establishes an organization-scoped cryptographic boundary.

During creation:

1. The secure enclave generates the Entity Master Key.
2. The enclave derives organization keys for metadata encryption and search.
3. Organization metadata is stored encrypted.
4. The creator receives admin membership.
5. Literal stores encrypted outputs and opaque tokens, not plaintext organization metadata.

Endpoint: POST /admin/entities

Entity creation is currently an admin operation that requires admin credentials. After successful creation, the creator is automatically assigned the admin role on the new entity and can immediately add members.

Step 2 — Add Members

An entity admin creates a pending membership for the intended member. Literal stores the membership with opaque tokens and commitments rather than plaintext relationship fields.

The claim process is bound to the intended member’s key material through hash-lock commitments. This prevents another party from claiming the membership if they discover the invitation.

Endpoint: POST /v1/entities/{id}/memberships

Only entity admins can create memberships.

Step 3 — Claim Membership

The invited member completes onboarding by proving possession of the expected signing key. During claim, the member also registers delivery public keys used for organization-scoped document deliveries.

After a successful claim:

• The membership becomes active.
• The member can decrypt organization metadata client-side.
• The member can participate in organization-scoped workflows.
• Document access still requires grants, deliveries, or other authorized sharing paths.

Endpoint: PUT /v1/entities/{id}/memberships/{membershipId}/claim

Step 4 — Queue Organization-Scoped Indexing When Needed

If existing documents should become searchable in the organization scope, queue an indexing job. The secure enclave generates organization-scoped blind index tokens. Documents become searchable as the job completes.

Endpoint: POST /v1/users/index-jobs

Membership alone does not imply that all personal documents should be indexed into the organization. Queue indexing only for the documents that should appear in organization search.

List Organizations

Members can list organizations they belong to. Literal returns encrypted organization metadata, which the client decrypts locally with the member’s wrapped entity key.

Endpoint: GET /v1/entities

Manage Members

Admins can list and remove members.

Endpoints:

• GET /v1/entities/{id}/memberships
• DELETE /v1/entities/{id}/memberships/{membershipId}

Removing a member revokes their membership and access to future organization-scoped operations. Document access granted through separate grants or deliveries should be handled according to those access paths.

Roles And Permissions

After Onboarding

After members have claimed access, organizations can:

• Upload encrypted documents using Document Upload.
• Share access using Creating And Claiming Grants.
• Deliver encrypted document access to members using Entity Deliveries.
• Generate organization-scoped search tokens through indexing jobs.
• Search shared organization documents using Searching Over Encrypted Documents.

Troubleshooting

• If member creation fails, confirm the caller has admin privileges.
• If membership claim fails, confirm the member is using the expected key material.
• If organization metadata cannot be decrypted, confirm the member has claimed membership and is using the current wrapped entity key.
• If documents do not appear in organization search, confirm organization-scoped indexing has completed.

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

Related Resources

• Entities & Memberships — the conceptual model behind entities and zero-knowledge membership.
• Key Hierarchy — how organization-level keys are structured.
• Entity Deliveries — push encrypted document access directly to a member.
• Creating And Claiming Grants — share documents through time-limited grants.
• Searching Over Encrypted Documents — generate search tokens once organization indexing completes.

Last updated on