Create a tenant with the Node.js SDK
permit.api.tenants.create() creates a tenant in the Permit.io environment that your Node.js SDK client is connected to. A tenant is an isolated group of users and resources, such as one customer organization in a multi-tenant app. This reference is for backend developers who create tenants from code, for example when a customer signs up.
Prerequisites
- A
permitclient created with an API key for the environment. See Create a Permit client and Get your API key.
Method signature
| Method | Signature | Status |
|---|---|---|
permit.api.tenants.create | create(tenantData: TenantCreate): Promise<TenantRead> | Recommended |
permit.api.createTenant | createTenant(tenant: TenantCreate): Promise<TenantRead> | Deprecated alias with the same argument |
Parameters
The method takes one argument: a TenantCreate object. Pass the object itself, not a JSON string.
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Unique, URL-friendly identifier of the tenant (a slug). Use the key in permission checks and later API calls. |
name | string | Yes | Display name of the tenant. |
description | string | No | Longer description of the tenant. |
attributes | object | No | Tenant attributes that attribute-based access control (ABAC) policies can evaluate. |
Example TenantCreate object:
{
key: "key",
name: "name",
description: "description",
attributes: {}
}
Example
const response = await permit.api.tenants.create(tenant);
Return value
The method resolves to a TenantRead object: the fields you sent, plus id, organization_id, project_id, environment_id, created_at, updated_at, and last_action_at.
If the Permit API returns an error status code, permit.api.tenants.create() throws a PermitApiError. The deprecated permit.api.createTenant() rethrows the underlying Axios error.