Multi-tenancy

If you run a platform on Namespace, your customers should never see each other’s work. Tenants make that separation part of the infrastructure: each customer gets their own tenant, and everything they run lives inside it.

What is a tenant?

A tenant is an isolated space in Namespace that owns resources: instances, builds, volumes, caches, secrets, and the credentials that access them. The rest of Namespace calls the same thing a workspace. Tenants are isolated from each other:

Resources created in one tenant are invisible to every other tenant.
A tenant’s credentials only work inside that tenant.
Limits, such as how many instances can run at once, apply to each tenant separately.

A typical platform creates one tenant per customer, so each customer’s data and workloads stay separate from every other customer’s.

How your platform and its tenants work together

Your platform manages tenants with partner credentials. With them, it can:

Create a tenant for each new customer.
List and find the tenants it owns.
Update a tenant’s name and labels.
Set policies that limit what a tenant can use.
Delete a tenant when a customer leaves.
Issue tenant tokens that act inside a tenant.

Work inside a tenant happens with a tenant credential. Your platform uses one to act for a customer, and it can give customers their own. With a tenant credential you can:

Run instances, builds, and other workloads.
Use storage, such as cache volumes, the container registry, and secrets.
Read the tenant’s policies.
Create revokable tokens for systems outside your platform.

In code, these two roles are a partner client and a tenant client. Partner and tenant clients explains how to create each one.

What a tenant looks like

{
  "id": "tenant_lqrj7qre0ts32",
  "createdAt": "2026-09-29T13:58:19.121800Z",
  "visibleName": "Customer 1",
  "externalAccountId": "customer-1",
  "labels": [{ "name": "plan", "value": "pro" }]
}

Field	Description
`id`	Namespace’s ID for the tenant, starting with `tenant_`. You use it to update, delete, and issue tokens for the tenant.
`externalAccountId`	Your ID for the customer, such as the account ID from your own database. Each ID maps to at most one tenant, and it cannot be changed after creation.
`visibleName`	A display name shown in Namespace interfaces such as the dashboard.
`labels`	Name and value pairs for your own metadata, such as a customer’s plan or region.
`createdAt`	When the tenant was created.

Build with Namespace

Building Blocks

What is a tenant?

How your platform and its tenants work together

What a tenant looks like

Next steps

Quickstart

Authentication

​What is a tenant?

​How your platform and its tenants work together

​What a tenant looks like

​Next steps

Quickstart

Authentication

What is a tenant?

How your platform and its tenants work together

What a tenant looks like

Next steps