Complete first-run setup

POST

/v1/setup/complete

curl --request POST \
  --url https://example.com/v1/setup/complete \
  --header 'Content-Type: application/json' \
  --data '{ "tenant_name": "example", "tenant_slug": "example", "domains": [ "example" ], "admin_email": "example", "admin_name": "example", "admin_password": "example", "oidc_config": { "issuer_url": "example", "client_id": "example", "client_secret": "example", "scopes": [ "example" ] }, "aws_identity_center": { "sso_instance_arn": "example", "role_arn": "example", "region": "example" }, "platform_mode": "single", "mfa_required": true }'

Request Body ^required

Media type application/json

object

tenant_name

required

string

tenant_slug

required

string

domains

Email domains to register for the tenant.

Array<string>

admin_email

required

string

admin_name

required

string

admin_password

required

string

oidc_config

Optional OIDC provider configuration.

object

issuer_url

string

client_id

string

client_secret

string

scopes

Array<string>

aws_identity_center

Optional AWS Identity Center configuration.

object

sso_instance_arn

string

role_arn

string

region

string

platform_mode

Deployment mode — single-tenant or multi-tenant platform.

string

default: single

Allowed values: single multi

mfa_required

Whether MFA is required for all users. Defaults to true if omitted.

boolean

Responses

201

Setup completed

Media type application/json

object

tenant

required

object

id

required

string format: uuid

name

required

string

slug

required

string

locale

required

Default locale for the tenant (e.g. ‘en’, ‘fr’).

string

owner_email

Email address of the tenant owner.

string

nullable

owner_user_id

UUID of the tenant’s owner user.

string format: uuid

nullable

sso_start_url

AWS IAM Identity Center start URL for SSO login.

string

nullable

sso_region

AWS region of the IAM Identity Center instance.

string

nullable

created_at

required

string format: date-time

updated_at

required

string format: date-time

is_master

required

Whether this tenant is the master (platform) tenant.

boolean

primary_domain

First verified domain for this tenant, if any.

string

nullable

message

required

string

domains

Domains created during setup (unverified). Includes DNS verification instructions.

Array<object>

object

id

required

string format: uuid

domain

required

string

verified

required

boolean

verified_at

string format: date-time

nullable

verification_token

required

string

dns_record

required

string

dns_value

required

string

created_at

required

string format: date-time

Example ^generated

{
  "tenant": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "name": "example",
    "slug": "example",
    "locale": "example",
    "owner_email": "example",
    "sso_start_url": "example",
    "sso_region": "example",
    "created_at": "2026-04-15T12:00:00Z",
    "updated_at": "2026-04-15T12:00:00Z"
  },
  "message": "example",
  "domains": [
    {
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "domain": "example",
      "verified": true,
      "verified_at": "2026-04-15T12:00:00Z",
      "verification_token": "example",
      "dns_record": "example",
      "dns_value": "example",
      "created_at": "2026-04-15T12:00:00Z"
    }
  ]
}

400

Invalid input

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}

409

Setup already completed

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}

422

A submitted domain is blocked (common email provider).

Media type application/json

object

code

required

Machine-readable error code (e.g. “not_found”, “tenant_mismatch”).

string

message

required

Human-readable description of the error.

string

details

Optional additional context about the error.

object

key

additional properties

any

notices

Policy notices from determining Cedar rules, if applicable.

Array<string>

Example ^generated

{
  "code": "example",
  "message": "example",
  "details": {},
  "notices": [
    "example"
  ]
}