Skip to content
Authrim

Create a tenant.

POST
/api/admin/tenants
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/admin/tenants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "id": "acme", "name": "Acme Corp", "isolation_policy": "tenant_exclusive" }'

Create a tenant as a platform-level administrator. The server assigns lifecycle state, default status, and timestamps; callers provide only the tenant identifier and display metadata. This endpoint does not use X-Tenant-Id because the target tenant is being created.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json

Tenant creation input. The server sets lifecycle_state, is_default, created_at, and updated_at; those fields must not be supplied by callers.

object
id
required

Stable tenant identifier. Must be a DNS-label-style lowercase value.

string
>= 1 characters <= 63 characters /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
tenant_code

Optional human-facing tenant code. Defaults to id when omitted.

string
>= 1 characters <= 63 characters /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
name
required
string
>= 1 characters <= 200 characters
description
string
<= 500 characters
isolation_policy

Physical tenant data placement. Shared pool databases may host multiple tenants; tenant-exclusive databases accept only this tenant. Both modes expand automatically.

string
default: tenant_exclusive
Allowed values: shared_pool tenant_exclusive
key
additional properties
Examples

Create a tenant with the default tenant code.

{
  "id": "acme",
  "name": "Acme Corp",
  "isolation_policy": "tenant_exclusive"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Tenant mutation response. Timestamps and lifecycle fields are assigned by the server and are not accepted in the create request body.

Media type application/json

Tenant row returned by create, update, set-default, and other tenant mutation operations.

object
id
required
string
tenant_code
required
string
name
required
string
description
required
string | null
isolation_policy
required

Physical placement scope. Both modes expand automatically.

string
Allowed values: shared_pool tenant_exclusive
lifecycle_state
required
string
Allowed values: provisioning active suspended frozen migration_read_only deleting deleted restore_pending restore_validating
is_default
required
boolean
created_at
required

Unix timestamp in seconds.

integer format: int64
updated_at
required

Unix timestamp in seconds.

integer format: int64
provisioning

Present when tenant creation is accepted for asynchronous Control provisioning.

object
mode
string
Allowed values: control-plane
operation_id
required
string
tenant_id
required
string
operation_kind
required
string
Allowed values: create clone
source_tenant_id
required
string | null
isolation_policy
required
string
Allowed values: shared_pool tenant_exclusive
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
current_step
required
string
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
created_at
required
integer format: int64
updated_at
required
integer format: int64
completed_at
required
integer | null format: int64
preparation_result
required
object | null
capacity_operation_ids
required
object
key
additional properties
string
capacity_operations
Array<object>
object
data_role
required
string
Allowed values: tenant_core/default tenant_core/users tenant_pii
operation_id
required
string
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
updated_at
required
integer format: int64
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
key
additional properties
Examples
Example controlPlane

Tenant accepted for asynchronous Control Worker provisioning.

{
  "id": "acme",
  "tenant_code": "acme",
  "name": "Acme Corp",
  "description": "Production tenant for Acme Corp.",
  "isolation_policy": "tenant_exclusive",
  "lifecycle_state": "provisioning",
  "is_default": false,
  "created_at": 1770000000,
  "updated_at": 1770000000,
  "provisioning": {
    "operation_id": "tenant_create_018f3f7c85b07c5da6b61c3a6e6b9e01",
    "tenant_id": "acme",
    "operation_kind": "create",
    "isolation_policy": "tenant_exclusive",
    "status": "queued",
    "current_step": "request_accepted",
    "attempt_count": 0,
    "next_attempt_at": null,
    "last_error_code": null,
    "created_at": 1770000000,
    "updated_at": 1770000000,
    "completed_at": null,
    "capacity_operation_ids": {},
    "steps": []
  }
}

202

Section titled “202 ”

Tenant creation was accepted for asynchronous Control Worker provisioning.

Media type application/json
object
id
required
string
tenant_code
required
string
name
required
string
description
required
string | null
isolation_policy
required

Physical placement scope. Both modes expand automatically.

string
Allowed values: shared_pool tenant_exclusive
lifecycle_state
required
string
Allowed values: provisioning active suspended frozen migration_read_only deleting deleted restore_pending restore_validating
is_default
required
boolean
created_at
required

Unix timestamp in seconds.

integer format: int64
updated_at
required

Unix timestamp in seconds.

integer format: int64
provisioning
required

Present when tenant creation is accepted for asynchronous Control provisioning.

object
mode
string
Allowed values: control-plane
operation_id
required
string
tenant_id
required
string
operation_kind
required
string
Allowed values: create clone
source_tenant_id
required
string | null
isolation_policy
required
string
Allowed values: shared_pool tenant_exclusive
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
current_step
required
string
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
created_at
required
integer format: int64
updated_at
required
integer format: int64
completed_at
required
integer | null format: int64
preparation_result
required
object | null
capacity_operation_ids
required
object
key
additional properties
string
capacity_operations
Array<object>
object
data_role
required
string
Allowed values: tenant_core/default tenant_core/users tenant_pii
operation_id
required
string
status
required
string
Allowed values: queued running waiting_retry blocked succeeded canceled
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
updated_at
required
integer format: int64
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
steps
required
Array<object>
object
step_key
required
string
Allowed values: request_accepted capacity_check reserve_default_route tenant_seed registry_publish tenant_smoke tenant_prepare lookup_activate tenant_active
status
required
string
Allowed values: queued running waiting_retry blocked succeeded skipped canceled rolled_back
attempt_count
required
integer
next_attempt_at
required
integer | null format: int64
last_error_code
required
string | null
observed_resource_id
required
string | null
progress_current
integer | null
progress_total
integer | null
started_at
required
integer | null format: int64
completed_at
required
integer | null format: int64
updated_at
required
integer format: int64
key
additional properties
key
additional properties
Example 
{
  "id": "acme",
  "tenant_code": "acme",
  "name": "Acme Corp",
  "description": "Production tenant for Acme Corp.",
  "isolation_policy": "tenant_exclusive",
  "lifecycle_state": "active",
  "is_default": false,
  "created_at": 1770000000,
  "updated_at": 1770000000
}