Create Tenants

When a customer signs up for your platform, give them a tenant. You link each tenant to your own ID for the customer, called the external account ID, so you can always get back to it without storing Namespace IDs. Creating tenants requires a partner client. The examples start from partnerClient.

Create a tenant

CreateTenant creates a new tenant for a customer.

const { tenant } = await partnerClient.tenants.createTenant({
  externalAccountId: "customer-1",
  visibleName: "Customer 1",
  labels: [{ name: "plan", value: "pro" }],
});

console.log(tenant!.id);

import "namespacelabs.dev/integrations/proto/namespace/stdlib"

resp, err := partnerClient.Tenants.CreateTenant(ctx, &iamv1beta.CreateTenantRequest{
	ExternalAccountId: "customer-1",
	VisibleName:       "Customer 1",
	Labels:            []*stdlib.Label{{Name: "plan", Value: "pro"}},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(resp.Tenant.Id)

Output

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

Each external account ID can belong to only one tenant. If a tenant with the same external account ID already exists, CreateTenant fails with a FailedPrecondition error instead of returning it. That makes it a good fit for a signup flow that should run only once per customer, where a duplicate means something went wrong.

Get or create a tenant

EnsureTenantForExternalAccount returns the tenant for an external account ID, creating it if it does not exist yet. Because it is safe to call repeatedly, you can call it whenever you need a customer’s tenant, for example at the start of every job you run for them.

const { tenant } = await partnerClient.tenants.ensureTenantForExternalAccount({
  externalAccountId: "customer-1",
  visibleName: "Customer 1",
  labels: [{ name: "plan", value: "pro" }],
});

resp, err := partnerClient.Tenants.EnsureTenantForExternalAccount(ctx, &iamv1beta.EnsureTenantForExternalAccountRequest{
	ExternalAccountId: "customer-1",
	VisibleName:       "Customer 1",
	Labels:            []*stdlib.Label{{Name: "plan", Value: "pro"}},
})

The response has the same shape as for CreateTenant. Calling it again with the same external account ID returns the same tenant.

When the tenant already exists, the call also applies the name and labels you send, and the labels replace the tenant’s existing labels. Send the same name and labels every time, or leave labels out only if the tenant should have none.

Choose an external account ID

Namespace treats the external account ID as an opaque string, so use whatever identifies the customer in your own system, such as an account ID from your database. It cannot be changed after the tenant is created, so avoid values that might change, such as an email address.

Set limits when you create a tenant

Both calls accept policies, which limit what the tenant can use, such as how many instances it can run at once. Tenant policies explains the policies you can set. They work the same at creation as when you set them later.

Build with Namespace

Building Blocks

Create a tenant

Get or create a tenant

Choose an external account ID

Set limits when you create a tenant

Next steps

List and find tenants

Tenant tokens

​Create a tenant

​Get or create a tenant

​Choose an external account ID

​Set limits when you create a tenant

​Next steps

List and find tenants

Tenant tokens

Create a tenant

Get or create a tenant

Choose an external account ID

Set limits when you create a tenant

Next steps