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

> One-call signup provisioning (tenant + owner + app + API key): CustomDomain™ API reference in the tenancy group. Covers parameters, request body and responses.

Source: https://docs.customdomain.ai/docs/api-reference/tenancy/provisionTenant

## `POST https://api.customdomain.ai/v1/tenants:provision`

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.

### Authentication

`provisionSecret`

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant_name` | string | yes |  |
| `app_name` | string | no |  |
| `owner_email` | string | no |  |
| `environment` | `production`, `staging`, `development` | no |  |

### Responses

| Status | Description |
| --- | --- |
| `201` | Provisioned (api_key + client_secret shown once) |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `503` | Error envelope: {code, title, details}. |

### `201` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant_id` | string | yes |  |
| `application_id` | string | yes |  |
| `api_key` | string | yes | cd_live_… or cd_test_…; shown once |
| `client_secret` | string | yes | mints widget JWTs; shown once |
| `default_api_key` | string | no | The workspace default key, cd_live_… or cd_test_…; shown once. Absent when it could not be made. |
| `default_api_key_id` | string | no | The default key's id; present with default_api_key. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.