Auth API reference

Auth API · Consumer-Tenants

post/{app_slug}/v1/tenantsAuth

Create 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*string

Slug of the app.

Headers

Idempotency-Keystring

Retry 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*string

Human-readable display name shown in the customer UI.

Example: "Acme Co"

slugstring

Optional URL-safe slug, unique per app (case-insensitive). When omitted, derived from display_name; collisions retried with a random suffix.

Example: "acme-co"

metadataobject

Free-form metadata; opaque to Auth. Customer-controlled.

Example: {"plan":"pro","region":"eu-west"}

Response · 201 Tenant created.

id*string

Unique identifier of the tenant.

display_id*string

Short, human-friendly id of the tenant (shown in the console).

Example: "tnt_3a9f2b1c0d4e"

app_id*string

The Auth app the tenant belongs to.

slug*string

URL-safe identifier of the tenant, unique within its parent.

Example: "acme-org"

display_name*string

Human-readable name of the tenant.

Example: "Acme Org"

status*object

Tenant status: `active`, `suspended` or `archived`.

metadata*object

Free-form JSON object you attach to the tenant; returned as stored.

created_at*string · date-time

When the tenant was created (ISO 8601).

updated_at*string · date-time

When 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"
}