postProvision an admitted enterprise
enterprises.provisionAuthentication: 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 /enterprises/{enterprise_id}/provisionRequest Body
{
"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
Response
{
"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"
}
]
}Resource created successfully.
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 404 schema
Content type: application/json.
See response 401 schema.
Response 409 schema
Content type: application/json.
See response 401 schema.
Response 500 schema
Content type: application/json.
See response 401 schema.
Response 502 schema
Content type: application/json.
See response 400 schema.
Response 503 schema
Content type: application/json.
See response 400 schema.