Tenants and isolation
A tenant is the boundary around one customer’s data: their workspaces, documents, vector collections, models, jobs and users. Every request belongs to exactly one.
Your credentials decide the tenant
Section titled “Your credentials decide the tenant”The Gateway resolves the tenant from the credential you present — the tenant that owns your API key, or the tenant claim inside a user’s JWT — and injects that context before the request reaches any service.
You cannot choose the tenant with a header. The Gateway overwrites X-Tenant-Id on every
request with the value it derived from your credential. Sending your own is not an error; it simply
has no effect. This is deliberate: if a header could select the tenant, anyone with one valid
credential could read every tenant on the platform.
Isolation is then enforced again further down, including as row-level security in the database that fails closed — if the tenant context is somehow missing, queries match nothing rather than everything.
What this means when you build
Section titled “What this means when you build”One key per tenant you integrate with. If your product serves several RiddlerAI customers, you hold one key per customer and select the key, not a parameter, to choose whose data you touch. There is no cross-tenant query.
A missing resource may be a permission boundary — and so may a 403. Which status you get for another tenant’s resource depends on the service, so handle both:
| Area | Cross-tenant response |
|---|---|
| Workspaces and other Core OS resources | 404 — the row is filtered out before the handler sees it |
| Vector collections | 403 with an explanatory message |
| Tenant and customer administration | 403 |
The 404 form is the better behaviour, because a 403 confirms the resource exists and lets
someone probe for other tenants’ identifiers. Where you see 403 today, treat it as a boundary
rather than something to retry with different credentials.
The practical rule for your code: do not infer from a 404 that an identifier is malformed, and
do not treat 403 as necessarily meaning your own permissions are wrong.
Workspaces subdivide a tenant, they do not isolate it. Workspaces organise data within one customer. They are not a security boundary between customers; the tenant is.
Customers within a tenant
Section titled “Customers within a tenant”Some tenants represent an organisation that itself has customers. Those get customer-scoped API keys, which see only that customer’s slice rather than the whole tenant. If you are integrating on behalf of one end customer, a customer-scoped key is the narrower and better choice.
Working across several tenants
Section titled “Working across several tenants”A person can currently belong to only one tenant, so an integrator working across several holds several keys and manages them yourself.
Multi-tenant developer accounts — one login with access to several tenants, and a switcher rather than separate credentials — are being built. Until then, keep a key per tenant and label them clearly.