postApprove approval
approvals.decideAuthentication: Send Authorization: Bearer <access_token>.
MFA assurance: approval.decide. A step-up challenge returns insufficient_user_authentication; authenticate at the requested assurance before retrying.
Records an eligible human approval on a pending case. The caller needs approvals.decide, scope coverage and any role named in the requirement snapshot; initiator_cannot_approve excludes the initiator when enabled. The case stays pending until enough distinct human approvals are collected, then becomes approved. MFA assurance applies to this decision surface; a step-up challenge is returned when the current session does not meet the resolved requirement.
Parameters
| Name | Location | Type | Required | Description and constraints |
|---|---|---|---|---|
approval_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
Optional request body.
Request body schema
| Field | Type | Required | Description and constraints |
|---|---|---|---|
reason |
string or null | No |
Additional fields are not accepted.
Request body schema.reason
At least one alternative must match.
Request body schema.reason: alternative 1
Type: string.
Request body schema.reason: alternative 2
Type: null.
Request URL
POST /approvals/{approval_id}/approveRequest Body
{
"reason": "Reviewed request"
}Responses
Response
{
"action_family": "withdrawal",
"collected_human_approvals": 1,
"created_at": "2026-05-01T10:00:00Z",
"decision": {
"decided_at": "2026-05-01T10:00:00Z",
"decided_by": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "11111111-1111-4111-8111-111111111111",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"enterprise_binding": {
"tenant_type": "enterprise",
"topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"federation": null,
"identity_source": "platform-managed",
"initiated_by": null,
"subject": {
"id": "11111111-1111-4111-8111-111111111111",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"reason": "Approved after review"
},
"expires_at": "2026-05-02T10:00:00Z",
"governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"initiated_by": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"enterprise_binding": {
"tenant_type": "enterprise",
"topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"federation": null,
"identity_source": "platform-managed",
"initiated_by": null,
"subject": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"requirement_snapshot": {
"authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"expires_at": "2026-05-02T10:00:00Z",
"governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"initiator_cannot_approve": true,
"reason_code": "high_value",
"required_human_approvals": 1,
"requirement_key": "withdrawal_approval",
"source": "policy"
},
"resource": "approval",
"status": "approved",
"updated_at": "2026-05-01T10:00:00Z"
}Operation succeeded.
Response 200 schema
Content type: application/json.
application/json body
| Field | Type | Required | Description and constraints |
|---|---|---|---|
action_family |
string | Yes | minLength: 1 |
collected_human_approvals |
integer | Yes | minimum: 0; maximum: 9007199254740991 |
created_at |
string | Yes | 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))$ |
decision |
object or null | No | |
expires_at |
string | Yes | 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))$ |
governed_ref |
string or string | Yes | |
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
initiated_by |
object | Yes | No additional fields |
operation_id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
requirement_snapshot |
object | Yes | No additional fields |
resource |
"approval" | Yes | |
status |
"pending" / "approved" / "rejected" / "cancelled" / "expired" | Yes | |
subject_display |
object or null | No | |
subject_ref |
string or null | No | |
updated_at |
string | Yes | 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))$ |
Additional fields are not accepted.
application/json body.decision
At least one alternative must match.
application/json body.decision: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
decided_at |
string or null | No | |
decided_by |
object or null | No | |
reason |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_at
At least one alternative must match.
application/json body.decision: alternative 1.decided_at: alternative 1
Type: string. 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))$
application/json body.decision: alternative 1.decided_at: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
actor |
object or null | Yes | |
approved_by |
object or null | Yes | |
authenticated_principal |
object | Yes | No additional fields |
enterprise_binding |
object | Yes | No additional fields |
federation |
object or null | Yes | |
identity_source |
"platform-managed" / "federated" / "system" | Yes | |
initiated_by |
object or null | Yes | |
subject |
object or null | Yes |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.actor
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.actor: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.approved_by: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.authenticated_principal.tenant_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding
| Field | Type | Required | Description and constraints |
|---|---|---|---|
tenant_type |
"enterprise" / "platform_operator" | Yes | |
topology_ref |
string or null | Yes |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.enterprise_binding.topology_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.federation
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
external_subject |
string | Yes | minLength: 1 |
issuer |
string | Yes | minLength: 1 |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.federation: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.initiated_by: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.subject
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref
At least one alternative must match.
application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 1.subject: alternative 2
Type: null.
application/json body.decision: alternative 1.decided_by: alternative 2
Type: null.
application/json body.decision: alternative 1.reason
At least one alternative must match.
application/json body.decision: alternative 1.reason: alternative 1
Type: string.
application/json body.decision: alternative 1.reason: alternative 2
Type: null.
application/json body.decision: alternative 2
Type: null.
application/json body.governed_ref
At least one alternative must match.
application/json body.governed_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.governed_ref: alternative 2
Type: string. pattern: ^(master-accounts|client-accounts)\/([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})$
application/json body.initiated_by
| Field | Type | Required | Description and constraints |
|---|---|---|---|
actor |
object or null | Yes | |
approved_by |
object or null | Yes | |
authenticated_principal |
object | Yes | No additional fields |
enterprise_binding |
object | Yes | No additional fields |
federation |
object or null | Yes | |
identity_source |
"platform-managed" / "federated" / "system" | Yes | |
initiated_by |
object or null | Yes | |
subject |
object or null | Yes |
Additional fields are not accepted.
application/json body.initiated_by.actor
At least one alternative must match.
application/json body.initiated_by.actor: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.initiated_by.actor: alternative 1.tenant_ref
At least one alternative must match.
application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.actor: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.initiated_by.actor: alternative 2
Type: null.
application/json body.initiated_by.approved_by
At least one alternative must match.
application/json body.initiated_by.approved_by: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.initiated_by.approved_by: alternative 1.tenant_ref
At least one alternative must match.
application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.approved_by: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.initiated_by.approved_by: alternative 2
Type: null.
application/json body.initiated_by.authenticated_principal
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.initiated_by.authenticated_principal.tenant_ref
At least one alternative must match.
application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.authenticated_principal.tenant_ref: alternative 2
Type: null.
application/json body.initiated_by.enterprise_binding
| Field | Type | Required | Description and constraints |
|---|---|---|---|
tenant_type |
"enterprise" / "platform_operator" | Yes | |
topology_ref |
string or null | Yes |
Additional fields are not accepted.
application/json body.initiated_by.enterprise_binding.topology_ref
At least one alternative must match.
application/json body.initiated_by.enterprise_binding.topology_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.enterprise_binding.topology_ref: alternative 2
Type: null.
application/json body.initiated_by.federation
At least one alternative must match.
application/json body.initiated_by.federation: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
external_subject |
string | Yes | minLength: 1 |
issuer |
string | Yes | minLength: 1 |
Additional fields are not accepted.
application/json body.initiated_by.federation: alternative 2
Type: null.
application/json body.initiated_by.initiated_by
At least one alternative must match.
application/json body.initiated_by.initiated_by: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.initiated_by.initiated_by: alternative 1.tenant_ref
At least one alternative must match.
application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.initiated_by: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.initiated_by.initiated_by: alternative 2
Type: null.
application/json body.initiated_by.subject
At least one alternative must match.
application/json body.initiated_by.subject: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
id |
string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ |
kind |
"user" / "service" / "system" | Yes | |
tenant_ref |
string or null | No |
Additional fields are not accepted.
application/json body.initiated_by.subject: alternative 1.tenant_ref
At least one alternative must match.
application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.initiated_by.subject: alternative 1.tenant_ref: alternative 2
Type: null.
application/json body.initiated_by.subject: alternative 2
Type: null.
application/json body.requirement_snapshot
| Field | Type | Required | Description and constraints |
|---|---|---|---|
approver_role_ref |
string or null | No | |
authority_ref |
string | Yes | pattern: ^(enterprises|platform-operators|clients)\/([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})$ |
expires_at |
string or null | No | |
governed_ref |
string or string | Yes | |
initiator_cannot_approve |
boolean | Yes | |
reason_code |
string | Yes | minLength: 1 |
required_human_approvals |
integer | Yes | maximum: 9007199254740991; exclusiveMinimum: 0 |
requirement_key |
string | Yes | minLength: 1 |
source |
"policy" | Yes |
Additional fields are not accepted.
application/json body.requirement_snapshot.approver_role_ref
At least one alternative must match.
application/json body.requirement_snapshot.approver_role_ref: alternative 1
Type: string. pattern: ^(roles)\/([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})$
application/json body.requirement_snapshot.approver_role_ref: alternative 2
Type: null.
application/json body.requirement_snapshot.expires_at
At least one alternative must match.
application/json body.requirement_snapshot.expires_at: alternative 1
Type: string. 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))$
application/json body.requirement_snapshot.expires_at: alternative 2
Type: null.
application/json body.requirement_snapshot.governed_ref
At least one alternative must match.
application/json body.requirement_snapshot.governed_ref: alternative 1
Type: string. pattern: ^(enterprises|platform-operators|clients)\/([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})$
application/json body.requirement_snapshot.governed_ref: alternative 2
Type: string. pattern: ^(master-accounts|client-accounts)\/([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})$
application/json body.subject_display
At least one alternative must match.
application/json body.subject_display: alternative 1
| Field | Type | Required | Description and constraints |
|---|---|---|---|
current_email |
string or null | Yes | |
new_email |
string or null | Yes |
Additional fields are not accepted.
application/json body.subject_display: alternative 1.current_email
At least one alternative must match.
application/json body.subject_display: alternative 1.current_email: alternative 1
Type: string. format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
application/json body.subject_display: alternative 1.current_email: alternative 2
Type: null.
application/json body.subject_display: alternative 1.new_email
At least one alternative must match.
application/json body.subject_display: alternative 1.new_email: alternative 1
Type: string. format: email; pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
application/json body.subject_display: alternative 1.new_email: alternative 2
Type: null.
application/json body.subject_display: alternative 2
Type: null.
application/json body.subject_ref
At least one alternative must match.
application/json body.subject_ref: alternative 1
Type: string. pattern: ^(users)\/([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})$
application/json body.subject_ref: alternative 2
Type: null.
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 |
"insufficient_user_authentication" | Yes | |
data |
object | Yes | No additional fields |
message |
string | Yes |
Additional fields are not accepted.
application/json body.data
| Field | Type | Required | Description and constraints |
|---|---|---|---|
acr_values |
string | Yes | |
max_age |
string | Yes |
Additional fields are not accepted.
| Response header | Type | Description |
|---|---|---|
WWW-Authenticate |
string | RFC 9470 challenge. acr_values is urn:yh:acr:mfa for mandatory MFA policy and urn:yh:acr:mfa-if-enrolled for optional critical-step-up policy. |
Response 403 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 404 schema
Content type: application/json.
See response 403 schema.
Response 409 schema
Content type: application/json.
See response 403 schema.
Response 500 schema
Content type: application/json.
See response 403 schema.
Response 502 schema
Content type: application/json.
See response 400 schema.
Response 503 schema
Content type: application/json.
See response 400 schema.