Skip to content

LearnOperate

Multi-tenancy

Tenant isolation

Serving many customers from one deployment while keeping each one’s documents, indexes, caches, keys and spend invisible to the others.

In DocSlurpIllustrated explainer

On this page
A query fenced to the projects its API key may reachTwo organizations share one deployment. Meridian has two projects, Growth plans and Legal contracts; Acme has one, Board minutes. Each project has its own vector database and its rows carry its project ID. A key reaches only projects in its own organization and, if it has an allowlist, only those listed. Selected: Meridian browser key, allowlist: Growth plans. Reaches Growth plans only. Legal contracts is in the same organization but not on the allowlist.API KEYMeridian server keyall projects in its orgMeridian browser keyallowlist: Growth plansMeridian browser keyempty allowlistAcme server keyall projects in its orgQUERY“Are we on track to beatour FY2027 earnings?”ORGANIZATION · MeridianProject: Growth plansown vector databaseproject_id on rowsProject: Legal contractsown vector databaseproject_id on rowsORGANIZATION · AcmeProject:Board minutesown vector database✓✕✕

Reaches Growth plans only. Legal contracts is in the same organization but not on the allowlist.

Every query is fenced by its key before it touches an index. The key fixes the organization and the allowed projects; search then opens only those projects’ own databases. Switch keys: a server key reaches its whole organization, a key from another organization reaches none of Meridian, and a public browser key with an empty allowlist reaches nothing at all.

The problem: one search box, many customers

A finance team uploads growth-plan-2027.pdf and q3-earnings-memo.pdf. In the same deployment, another company uploads its board minutes. Both search for “Are we on track to beat our FY2027 earnings?” The finance team must get its growth plan. The other company must get nothing from it, not a result, not a snippet in a chat answer, not even a faster response because the plan’s embedding was already cached.

That is multi-tenancy: one running system, many customers (tenants), and no path by which one tenant’s data, activity or spend becomes visible to another. It is cheaper to run than a separate deployment per customer, and every shared component is a place it can go wrong.

Tenants nest

Most document services have a hierarchy. In DocSlurp it is organization → users → projects → runs → documents. The organization is the tenant boundary: billing, members and API keys belong to it. Projects subdivide it by use case, such as “Growth plans” and “Legal contracts”, each with its own settings and index.

Isolation has to hold at both levels. An organization must never see another’s data. Inside one organization, a key meant for the public docs widget must not reach the legal project.

Every path needs a scope

There is no single wall. Each component that stores or returns data needs its own tenant scope:

Path What scoping looks like
Database queries Every query filters by organization or project ID taken from the authenticated caller, never from the request body alone.
Vector index Separate tables or databases per tenant, or a mandatory tenant filter on every search.
Caches The tenant ID is part of every cache key.
Object storage Files live under a tenant prefix, and signed URLs cover one object.
API keys A key belongs to one organization and can be narrowed to listed projects.
Webhooks and exports Events are delivered only while the subscriber can still read that project.
Usage and limits Spend is stamped with the tenant when written; rate limits count per key.

The vector index deserves a closer look. A shared table with a tenant_id filter is simple, but it relies on every query remembering the filter, and approximate nearest neighbor search with a selective filter can return fewer results than asked for (see metadata filtering). A table per tenant makes the scope structural: a query opens one table and physically cannot read another. The cost is more, smaller indexes to build and maintain.

How a query gets fenced

Follow one request in the figure. A browser key for the finance team’s help widget sends the question.

  1. The server resolves the key to its organization, Meridian, and its allowlist, Growth plans. Both come from the key record, not the request.
  2. The server checks the target project against the key: same organization, and on the allowlist. If either check fails, the request is refused.
  3. Search opens the vector database for that one project and runs keyword queries filtered by its ID.
  4. The query embedding is cached under a key that starts with the organization ID, so another tenant asking the same question gets a miss, with no telling difference in speed.
  5. Token usage is written with the organization, project and key attached.

Now switch keys in the figure. A server key reaches every project in its organization. A key from another organization reaches none of Meridian’s. And a browser key with an empty allowlist reaches nothing at all.

That last rule is the interesting one. A browser key is embedded in public web pages, so anyone can copy it. If “no allowlist” meant “everything”, a forgotten setting would publish the whole organization. Failing closed means a misconfigured public key is useless rather than dangerous.

Noisy neighbors

Isolation also covers performance. One tenant re-indexing 50,000 pages or an agent firing searches in a loop shouldn’t make everyone else slow. Common defenses:

  • Rate limiting per key and per IP.
  • Fair queues: when capacity is short, serve waiting work round-robin across tenants instead of first come, first served, so one tenant’s burst waits behind itself.
  • Per-tenant budgets that stop spend before it starts, checked against usage metering.

Where it breaks

  • Derived data escapes. Summaries, knowledge graph entities, suggested queries, cached answers and logs all carry tenant content. Each needs the same scope as the source documents.
  • Timing side channels. A shared cache can reveal that someone else searched for a phrase, because their hit makes your query faster. Keying by tenant removes the shared entry.
  • Background jobs lose context. A request carries its tenant, but a queue message, cron task or migration may not. Jobs should fail when the tenant is missing, not run unscoped.
  • Shared parsers. A malicious file parsed in a process that serves many tenants can reach them all. Isolate file processing too: see sandboxing.

When it matters

Always, for a hosted service. For a self-hosted single team it still matters inside the organization: projects separate data that different people or public widgets should see. Test isolation with negative tests: a key from another organization, a key narrowed to a different project, and a revoked key should each get nothing.

In DocSlurp

In DocSlurp

API keys reach only their own organization and, with an allowlist, only listed projects; a browser key with an empty allowlist reaches none (core/server/src/lib/api-key-project-scope.ts). With LanceDB, each project and embedding space has its own database (core/server/src/search/lancedb.ts), and search caches are keyed per organization (core/server/src/search/embedding-cache.ts).

Sources

Jump to