# Provision an admitted enterprise

Source: https://business-api-docs.youhodler.com/api/reference/enterprises/enterprises-provision

**Authentication:** Send `Authorization: Bearer <access_token>`.

Configures the designated administrator, roles and commercial agreements for an enterprise already created with `POST /enterprises`. Requires a platform-operator binding and an `enterprise_wildcard` grant anchored at `platform-operators/<id>` for `enterprises.provision`. Supply the contracted `service_types` and `platform_fee_bps`; `enterprise_fee_bps` defaults to 0. Provisioning is resumable: completed work is reported as `reused` on later runs. Production supports `first_access_method=enterprise_idp`; hosted magic-link and passkey first access are deployment-dependent. An `enterprise_idp` response reports `first_access.sent=false`; once its identity stack is ready, use the first-access resend endpoint to issue the command.

## Parameters

| Name | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `enterprise_id` | path | string | Yes | format: uuid |
| `Idempotency-Key` | header | string | No | Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128 |

## Request

Required request body.

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `designated_admin` | object | Yes | No additional fields |
| `effective_from` | string | No | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |
| `enterprise_fee_bps` | integer | No | minimum: 0; maximum: 10000; default: `0` |
| `first_access_method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" | No |  |
| `iam_hosting` | "enterprise" / "platform" | No |  |
| `platform_fee_bps` | integer | Yes | minimum: 0; maximum: 10000 |
| `service_types` | "custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"[] | Yes | minItems: 1 |

Additional fields are not accepted.

#### Request body schema.designated_admin

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `display_name` | string or null | No |  |
| `email` | string | Yes | format: email; pattern: `^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$`; maxLength: 254 |

Additional fields are not accepted.

##### Request body schema.designated_admin.display_name

At least one alternative must match.

###### Request body schema.designated_admin.display_name: alternative 1

Type: `string`. minLength: 1; maxLength: 200

###### Request body schema.designated_admin.display_name: alternative 2

Type: `null`. 

#### Request body schema.service_types

Type: `"custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"[]`. minItems: 1

##### Request body schema.service_types item

Type: `"custody" / "conversion" / "withdrawal_crypto" / "withdrawal_fiat" / "deposit_crypto" / "deposit_fiat" / "internal_transfer" / "staking"`.

**Request URL — POST**
```http
POST /enterprises/{enterprise_id}/provision
```

**Request Body — application/json**
```json
{
  "designated_admin": {
    "display_name": "Acme Admin",
    "email": "admin@acme.example"
  },
  "enterprise_fee_bps": 0,
  "first_access_method": "enterprise_idp",
  "iam_hosting": "enterprise",
  "platform_fee_bps": 10,
  "service_types": [
    "custody",
    "deposit_fiat",
    "withdrawal_fiat"
  ]
}
```

## Responses

**201 Resource created successfully**

Resource created successfully.

```json
{
  "admin_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "enterprise_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "first_access": {
    "method": "enterprise_idp",
    "sent": false
  },
  "human_actor_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "identity_provider_id": null,
  "integration_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "operator_role_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "steps": [
    {
      "status": "completed",
      "step": "human_actor"
    }
  ]
}
```

**400 Invalid request payload**

Invalid request payload, query, or parameter shape.

**401 Caller is not authenticated or the bearer token is invalid**

Caller is not authenticated or the bearer token is invalid.

**403 Caller lacks the required capability or permitted scope**

Caller lacks the required capability or permitted scope.

**404 Resource not found**

Resource not found.

**409 State conflict — the request cannot be applied to the current resource state**

State conflict — the request cannot be applied to the current resource state.

**500 An unexpected internal failure occurred**

An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.

**502 Upstream service returned an unexpected error**

Upstream service returned an unexpected error.

**503 Service is temporarily unavailable**

Service is temporarily unavailable; retry with backoff.
### Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `admin_role_id` | string | Yes |  |
| `enterprise_ref` | string | Yes | pattern: `^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$` |
| `first_access` | object | Yes | No additional fields |
| `human_actor_id` | string | Yes |  |
| `identity_provider_id` | string or null | Yes |  |
| `integration_role_id` | string or null | Yes |  |
| `operator_role_id` | string | Yes |  |
| `steps` | object[] | Yes |  |

Additional fields are not accepted.

##### application/json body.first_access

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `method` | "magic_link" / "passkey_enrolment" / "enterprise_idp" | Yes |  |
| `sent` | boolean | Yes |  |

Additional fields are not accepted.

##### application/json body.identity_provider_id

At least one alternative must match.

###### application/json body.identity_provider_id: alternative 1

Type: `string`. 

###### application/json body.identity_provider_id: alternative 2

Type: `null`. 

##### application/json body.integration_role_id

At least one alternative must match.

###### application/json body.integration_role_id: alternative 1

Type: `string`. 

###### application/json body.integration_role_id: alternative 2

Type: `null`. 

##### application/json body.steps

Type: `object[]`. 

###### application/json body.steps item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `status` | "completed" / "reused" | Yes |  |
| `step` | string | Yes |  |

Additional fields are not accepted.

### Response 400 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 401 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object or null | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 403 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 404 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 409 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 500 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 502 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).

### Response 503 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).
