Skip to main content
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: 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. You can still define a judgment on each tenant’s namespace instead, with one call per tenant, usually made when the tenant is provisioned:
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.