> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vainona.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-tenant platforms

> One namespace per tenant: isolated, independently billed, and free when idle.

If you serve tenants and want judgments per tenant, give each tenant its own namespace. Namespaces are the shard, the cache unit and the billing unit. A platform with 50,000 tenants has 50,000 namespaces and pays nothing for the ones nobody touches.

## Name namespaces as a hierarchy

Use the hierarchy for environment and tenant: `acme/prod/tenant_123`. Listing (`GET /namespaces?prefix=acme/prod/`), deletion and key scoping all work on prefixes. There is no project object: the hierarchy is the project structure.

## Scope keys by prefix or namespace

An API key can be restricted to a namespace prefix, or to one namespace, and a role. Give each backend service only what it needs:

| Key                                           | Can do                            |
| --------------------------------------------- | --------------------------------- |
| `read_write` scoped to `acme/prod/*`          | Everything in production          |
| `read_only` scoped to `acme/prod/*`           | Reads and queries only            |
| `read_write` scoped to `acme/staging/*`       | Nothing in production             |
| `read_write` scoped to `acme/prod/tenant_123` | That one tenant, and nothing else |

A prefix stops at a `/`. `acme/prod/tenant_1*` covers `acme/prod/tenant_1` and everything under `acme/prod/tenant_1/`, never `acme/prod/tenant_12`. For a tenant's own key, scope it to the tenant's namespace.

Keys belong to your organization, not to people. Create them on the dashboard's Keys page.

## Define judgments once for every tenant

Create the judgment on a prefix, such as `acme/prod/*`, and every namespace under it inherits it, including tenants created later. A tenant can override its thresholds and freshness policy, or detach the judgment into its own copy. See [templates](/guides/templates).

You can still define a judgment on each tenant's namespace instead, with one call per tenant, usually made when the tenant is provisioned:

```python theme={null}
for tenant in new_tenants:
    db.namespace(f"acme/prod/{tenant.id}").judgments.create(**needs_escalation_definition)
```

Each tenant then has its own definition and versions.

## Budgets per tenant

Each namespace can carry its own monthly compute budget, so one tenant's burst cannot run up your bill. When a tenant's namespace reaches its budget, its answers go `stale` and its writes continue, or, with `"on_exceeded": "reject"`, its writes are refused with `budget_exceeded`.

## Pinning and warming

Idle namespaces fall out of cache. The first query after that is cold and takes hundreds of milliseconds. Two tools help:

* **Warm** a namespace when you know a session is starting: `POST /namespaces/{ns}/warm` (`ns.warm()`). It is free and best-effort.
* **Pin** a namespace that must never be cold: `PATCH /namespaces/{ns}` with `{"pinned": true}`. It stays resident on two nodes and is billed as warm storage.