Skip to main content
POST
/
tenants
curl -X POST 'https://api.example.com/tenants' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Corp",
    "kind": "standard",
    "slug": "acme-corp",
    "planKey": "pro",
    "billingEmail": "billing@acme.com",
    "maxUsers": 50,
    "maxWorkspaces": 10
  }'

{
  "id": "tenant_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "Acme Corp",
  "kind": "standard",
  "scopeId": "scope_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c",
  "slug": "acme-corp",
  "planKey": "pro",
  "status": "active",
  "billingEmail": "billing@acme.com",
  "maxUsers": 50,
  "maxWorkspaces": 10,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Request Body

​
id
string
Optional client-provided ID. Format: tenant_{uuidv7}
​
name
string
required
Display name for the tenant
​
kind
string
required
Tenant kind. One of: standard, enterprise, trial
​
slug
string
required
URL-friendly unique identifier
​
externalId
string
External system identifier (e.g., Stripe customer ID)
​
ownerUserId
string
User ID of the tenant owner
​
billingEmail
string
Email for billing communications
​
technicalContactEmail
string
Email for technical communications
​
planKey
string
required
Subscription plan key (e.g., free, pro, enterprise)
​
maxUsers
number
Maximum number of users allowed
​
maxWorkspaces
number
Maximum number of workspaces allowed
​
maxProjects
number
Maximum number of projects allowed
​
maxEnvironments
number
Maximum number of environments allowed
​
metadata
object
Custom metadata

​
Response

Returns the created tenant object. Also creates an associated scope automatically. 
curl -X POST 'https://api.example.com/tenants' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Corp",
    "kind": "standard",
    "slug": "acme-corp",
    "planKey": "pro",
    "billingEmail": "billing@acme.com",
    "maxUsers": 50,
    "maxWorkspaces": 10
  }'

{
  "id": "tenant_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "Acme Corp",
  "kind": "standard",
  "scopeId": "scope_0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5c",
  "slug": "acme-corp",
  "planKey": "pro",
  "status": "active",
  "billingEmail": "billing@acme.com",
  "maxUsers": 50,
  "maxWorkspaces": 10,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}