---
title: "One-call signup provisioning (tenant + owner + app + API key)"
method: POST
path: "/tenants:provision"
tags: ["Tenancy"]
---

# One-call signup provisioning (tenant + owner + app + API key)

`POST /tenants:provision`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/tenants:provision`
- Auth: API key in header `X-Provision-Secret`

Atomically creates a tenant, its first owner member, a default application, and a long-lived API key. `api_key` and `client_secret` are returned ONCE. Guarded by the dedicated provision secret (the `X-Provision-Secret` header or a Bearer token) so the customer console's server can hold this narrow secret instead of the operator management key. It also mints the workspace default key (see `POST /tenants/{tenant_id}/default-key`) and returns it ONCE as `default_api_key` with its id; both fields are absent if it could not be made, and the default key route makes it later.

## Request body

- object
  - `tenant_name` string, required
  - `app_name` string
  - `owner_email` string
  - `environment` 'production' | 'staging' | 'development'

## Response `201`

Provisioned (api_key + client_secret shown once)

- object
  - `tenant_id` string, required
  - `application_id` string, required
  - `api_key` string, required: cd_live_… or cd_test_…; shown once
  - `client_secret` string, required: mints widget JWTs; shown once
  - `default_api_key` string: The workspace default key, cd_live_… or cd_test_…; shown once. Absent when it could not be made.
  - `default_api_key_id` string: The default key's id; present with default_api_key.

## Other responses

- `400`: Error envelope: {code, title, details}.
- `401`: Error envelope: {code, title, details}.
- `503`: Error envelope: {code, title, details}.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)