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
Reaches Growth plans only. Legal contracts is in the same organization but not on the allowlist.
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.
- The server resolves the key to its organization, Meridian, and its allowlist,
Growth plans. Both come from the key record, not the request. - The server checks the target project against the key: same organization, and on the allowlist. If either check fails, the request is refused.
- Search opens the vector database for that one project and runs keyword queries filtered by its ID.
- 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.
- 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).