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

# Create Tenants

> Give each of your customers their own tenant, and look it up again by your own customer ID.

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](/docs/platform/tenants/clients#partner-client). The examples start from `partnerClient`.

<h2 id="create">
  Create a tenant
</h2>

`CreateTenant` creates a new tenant for a customer.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { tenant } = await partnerClient.tenants.createTenant({
    externalAccountId: "customer-1",
    visibleName: "Customer 1",
    labels: [{ name: "plan", value: "pro" }],
  });

  console.log(tenant!.id);
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

```json Output theme={null}
{
  "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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  const { tenant } = await partnerClient.tenants.ensureTenantForExternalAccount({
    externalAccountId: "customer-1",
    visibleName: "Customer 1",
    labels: [{ name: "plan", value: "pro" }],
  });
  ```

  ```go Go theme={null}
  resp, err := partnerClient.Tenants.EnsureTenantForExternalAccount(ctx, &iamv1beta.EnsureTenantForExternalAccountRequest{
  	ExternalAccountId: "customer-1",
  	VisibleName:       "Customer 1",
  	Labels:            []*stdlib.Label{{Name: "plan", Value: "pro"}},
  })
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>

## 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](/docs/platform/tenants/policies) explains the policies you can set. They work the same at creation as when you set them later.

## Next steps

<Columns cols={2}>
  <Card title="List and find tenants" icon="list" href="/docs/platform/tenants/list">
    Look up the tenants your platform owns.
  </Card>

  <Card title="Tenant tokens" icon="ticket" href="/docs/platform/authentication/tenant-tokens">
    Act inside the new tenant.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.