/{app_slug}/v1/tenantsAuthCreate a tenant inside this app. Returns the new tenant with a `display_id` (`tnt_<12hex>`). PAK must hold auth.tenant.create.
Path parameters
app_slug*stringSlug of the app.
Headers
Idempotency-KeystringRetry safety: a repeat with the same key and body replays the first response instead of creating a tenant again. Same key with a different body: 409 `IDEMPOTENCY_KEY_REUSE`. 24 h window.
Request body
display_name*stringHuman-readable display name shown in the customer UI.
Example: "Acme Co"
slugstringOptional URL-safe slug, unique per app (case-insensitive). When omitted, derived from display_name; collisions retried with a random suffix.
Example: "acme-co"
metadataobjectFree-form metadata; opaque to Auth. Customer-controlled.
Example: {"plan":"pro","region":"eu-west"}
Response · 201 Tenant created.
id*stringUnique identifier of the tenant.
display_id*stringShort, human-friendly id of the tenant (shown in the console).
Example: "tnt_3a9f2b1c0d4e"
app_id*stringThe Auth app the tenant belongs to.
slug*stringURL-safe identifier of the tenant, unique within its parent.
Example: "acme-org"
display_name*stringHuman-readable name of the tenant.
Example: "Acme Org"
status*objectTenant status: `active`, `suspended` or `archived`.
metadata*objectFree-form JSON object you attach to the tenant; returned as stored.
created_at*string · date-timeWhen the tenant was created (ISO 8601).
updated_at*string · date-timeWhen the tenant was last changed (ISO 8601).
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/tenants
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"display_name": "Acme Co",
"slug": "acme-co",
"metadata": {
"plan": "pro",
"region": "eu-west"
}
}Response
{
"id": "string",
"display_id": "tnt_3a9f2b1c0d4e",
"app_id": "string",
"slug": "acme-org",
"display_name": "Acme Org",
"status": {},
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}