postIssue action token

Authentication: Send Authorization: Bearer <access_token>.

MFA assurance: action_token.issue. A step-up challenge returns insufficient_user_authentication; authenticate at the requested assurance before retrying.

Issues a short-lived action token that authorises a specific money-movement command. The token is bound to the caller and to the command digest of the requested action. Pass it in the X-Action-Token header when submitting the authorised command (e.g. POST /withdrawals). Pure service callers have no human-confirmation requirement and do not obtain action tokens: issuance requires a human subject and rejects a pure service subject with HTTP 403.

Enterprise/client human callers whose session does not satisfy the scope-level MFA assurance policy receive 401 with code = insufficient_user_authentication; follow the WWW-Authenticate header acr_values and max_age challenge, complete step-up at the IdP, then retry this request. Platform-bound humans always meet a mandatory MFA floor.

Request shapes, in order of preference:

  • { action: "<command>", command: { ... } } — edge validates the command and computes the digest server-side. Submit the same command values to the guarded endpoint. Object key order is canonicalized; withdrawal commands also normalize the money and destination fields before hashing. Supported commands:
    • withdrawal.create → POST /withdrawals
    • conversion.create → POST /conversions
    • external_settlement_conversion.create → POST /external-settlement-conversions
  • { action: "withdrawal.create", withdrawal: { ... } } — the original withdrawal-only field name, kept for compatibility; issues the same digest as the generic form.
  • { command_digest: "..." } — escape hatch for guarded commands with no structured variant yet. Callers must reproduce edge canonicalisation themselves, so prefer the structured form wherever one exists. Digests are hexadecimal SHA-256 values without a sha256: prefix.

Tokens are bound to the human subject and command, expire after five minutes and can be consumed once. Credential issuance bypasses durable idempotency response caching. Each request issues a fresh single-use token; retries must obtain and use a fresh token.

Request

Required request body.

Request body schema

At least one alternative must match.

Request body schema: alternative 1

Field Type Required Description and constraints
action "withdrawal.create" Yes
command object or object Yes

Additional fields are not accepted.

Request body schema: alternative 1.command

At least one alternative must match.

Request body schema: alternative 1.command: alternative 1
Field Type Required Description and constraints
account_ref string Yes 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})$
amount object Yes No additional fields
destination object No No additional fields
destination_id string No 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)$
network string No minLength: 1
rail "crypto" / "fiat" Yes

Additional fields are not accepted.

Request body schema: alternative 1.command: alternative 1.amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 1.command: alternative 1.destination
Field Type Required Description and constraints
address string Yes minLength: 1
memo string or null No

Additional fields are not accepted.

Request body schema: alternative 1.command: alternative 1.destination.memo

At least one alternative must match.

Request body schema: alternative 1.command: alternative 1.destination.memo: alternative 1

Type: string.

Request body schema: alternative 1.command: alternative 1.destination.memo: alternative 2

Type: null.

Request body schema: alternative 1.command: alternative 2
Field Type Required Description and constraints
account_ref string Yes 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})$
amount object Yes No additional fields
rail "fiat" Yes
withdrawal_destination_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)$

Additional fields are not accepted.

Request body schema: alternative 1.command: alternative 2.amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 2

Field Type Required Description and constraints
action "conversion.create" Yes
command object Yes No additional fields

Additional fields are not accepted.

Request body schema: alternative 2.command
Field Type Required Description and constraints
account_ref string Yes 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})$
client_idempotency_key string No minLength: 1
from_amount object Yes No additional fields
to_currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$

Additional fields are not accepted.

Request body schema: alternative 2.command.from_amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 3

Field Type Required Description and constraints
action "external_settlement_conversion.create" Yes
command object Yes No additional fields

Additional fields are not accepted.

Request body schema: alternative 3.command
Field Type Required Description and constraints
account_ref string Yes 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})$
client_idempotency_key string No minLength: 1
external_settlement_role "external_source_spend" / "external_target_disbursement" Yes
source_amount object Yes No additional fields
target_currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$

Additional fields are not accepted.

Request body schema: alternative 3.command.source_amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 4

Field Type Required Description and constraints
action "withdrawal.create" Yes
withdrawal object or object Yes

Additional fields are not accepted.

Request body schema: alternative 4.withdrawal

At least one alternative must match.

Request body schema: alternative 4.withdrawal: alternative 1
Field Type Required Description and constraints
account_ref string Yes 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})$
amount object Yes No additional fields
destination object No No additional fields
destination_id string No 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)$
network string No minLength: 1
rail "crypto" / "fiat" Yes

Additional fields are not accepted.

Request body schema: alternative 4.withdrawal: alternative 1.amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 4.withdrawal: alternative 1.destination
Field Type Required Description and constraints
address string Yes minLength: 1
memo string or null No

Additional fields are not accepted.

Request body schema: alternative 4.withdrawal: alternative 1.destination.memo

At least one alternative must match.

Request body schema: alternative 4.withdrawal: alternative 1.destination.memo: alternative 1

Type: string.

Request body schema: alternative 4.withdrawal: alternative 1.destination.memo: alternative 2

Type: null.

Request body schema: alternative 4.withdrawal: alternative 2
Field Type Required Description and constraints
account_ref string Yes 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})$
amount object Yes No additional fields
rail "fiat" Yes
withdrawal_destination_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)$

Additional fields are not accepted.

Request body schema: alternative 4.withdrawal: alternative 2.amount
Field Type Required Description and constraints
currency string Yes Currency code (ISO-4217 or on-chain ticker) pattern: ^[A-Z0-9]{1,16}$
value string Yes DecimalString pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$

Additional fields are not accepted.

Request body schema: alternative 5

Field Type Required Description and constraints
command_digest string Yes Pre-computed command digest. Escape hatch for guarded commands with no structured variant yet — prefer the action form, which covers withdrawal.create, conversion.create, external_settlement_conversion.create. minLength: 1

Additional fields are not accepted.

Request URL

POST
POST /action-tokens

Request Body

application/json
{
  "action": "conversion.create",
  "command": {
    "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "from_amount": {
      "currency": "USDT",
      "value": "100.00"
    },
    "to_currency": "BTC"
  }
}

Responses

Response

application/json
{
  "bound_actor": "users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "bound_command_digest": "a67a92ab1ea536ece3702cb97990040a45948c453aeb585e5ed1d8f2ce7734af",
  "expires_at": "2026-05-01T10:00:00Z",
  "token": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

Resource created successfully.

Response 201 schema

Content type: application/json.

application/json body

Field Type Required Description and constraints
bound_actor string Yes
bound_command_digest string Yes
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))$
token string Yes

Additional fields are not accepted.

Response header Type Description
Cache-Control "no-store"

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.