patchUpdate role
roles.manageAuthentication: Send Authorization: Bearer <access_token>.
Patches an active tenant-managed role. Requires the current If-Match entity tag. Platform-managed roles are immutable through this API; retired roles cannot be updated. Omitting a field preserves it; description: null clears the description, but name: null is refused. Permission changes invalidate affected principals’ authority context.
Parameters
| Name | Location | Type | Required | Description and constraints |
|---|---|---|---|---|
role_id |
path | string | Yes | format: uuid |
If-Match |
header | string | Yes | Weak entity tag from a prior GET. Mismatch causes the request to fail with 412 Precondition Failed. minLength: 1 |
Request
Required request body.
Request body schema
| Field | Type | Required | Description and constraints |
|---|---|---|---|
name |
string or null | No | |
description |
string or null | No | |
permissions |
"users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[] | No | minItems: 1 |
Additional fields are not accepted.
Request body schema.name
At least one alternative must match.
Request body schema.name: alternative 1
Type: string. minLength: 1
Request body schema.name: alternative 2
Type: null.
Request body schema.description
At least one alternative must match.
Request body schema.description: alternative 1
Type: string.
Request body schema.description: alternative 2
Type: null.
Request body schema.permissions
Type: "users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read"[]. minItems: 1
Request body schema.permissions item
Type: "users.read" / "users.invite" / "users.create" / "users.manage" / "users.activate_federated" / "users.recovery_initiate" / "service_accounts.read" / "service_accounts.create" / "service_accounts.manage" / "service_accounts.rotate_secret" / "clients.read" / "clients.create" / "clients.manage" / "accounts.read" / "accounts.create" / "accounts.manage" / "roles.read" / "roles.create" / "roles.manage" / "role_assignments.read" / "role_assignments.create" / "role_assignments.manage" / "withdrawals.read" / "withdrawals.create" / "withdrawals.manage" / "conversions.read" / "conversions.create" / "conversions.manage" / "external_settlement_conversions.read" / "external_settlement_conversions.create" / "external_settlement_conversions.manage" / "internal_transfers.read" / "internal_transfers.create" / "internal_transfers.manage" / "ramps.read" / "ramps.create" / "ramps.manage" / "policies.read" / "policies.create" / "policies.manage" / "commercial_agreements.read" / "commercial_agreements.create" / "commercial_agreements.manage" / "loans.read" / "loans.create" / "loans.manage" / "loan_products.read" / "loan_products.manage" / "loan_shortfalls.read" / "sandbox_simulator.run" / "sandbox_reset.run" / "webhooks.read" / "webhooks.create" / "webhooks.manage" / "funding_endpoints.read" / "funding_endpoints.provision" / "deposit_instructions.read" / "deposit_instructions.create" / "withdrawal_destinations.read" / "withdrawal_destinations.create" / "withdrawal_destinations.manage" / "deposits.read" / "deposits.credit" / "approvals.read" / "approvals.decide" / "compliance_assessments.read" / "compliance_assessments.decide" / "compliance_assessments.read_decision_volume" / "compliance_assessments.reveal_subject_identity" / "compliance_alerts.read" / "compliance_alerts.acknowledge" / "compliance_rules.read" / "compliance_rules.manage" / "events.read" / "feature_flags.read" / "feature_flags.manage" / "feature_flags.manage_platform" / "identity_providers.manage" / "enterprises.read" / "enterprises.list" / "enterprises.create" / "enterprises.provision" / "enterprises.manage" / "enterprises.restrict" / "enterprises.reactivate" / "enterprises.terminate" / "kyc.verify" / "payment_methods.manage" / "payout_methods.manage" / "crypto_networks.manage" / "platform_operators.read" / "platform_operators.manage" / "platform_principals.manage" / "platform_principals.rotate_secret" / "ledger.compensate" / "ledger.fee_post" / "ledger.reconciliation_post" / "overdraft_limits.manage" / "operations_reports.read" / "operations_reports.create_export" / "operations_reports.view_fee_breakdown" / "operations_reports.view_actor_attribution" / "audit.read" / "audit.create_export" / "audit.view_technical_traces" / "audit.view_actor_pii" / "audit.view_free_text" / "catalog.manage" / "custody_mappings.manage" / "onchain_analytics_mappings.manage" / "fiat_routes.manage" / "conversion_routes.manage" / "settlement_bindings.manage" / "legal.publish" / "operations.review" / "operations.recovery" / "admissibility.read" / "custody.read".
Request URL
PATCH /roles/{role_id}Request Body
{
"name": "Updated Role Name",
"description": "Updated description",
"permissions": [
"withdrawals.create"
]
}Responses
Response
{
"name": "Updated Role Name",
"description": "Updated description",
"created_at": "2026-05-01T10:00:00Z",
"etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"permissions": [
"withdrawals.create"
],
"platform_managed": false,
"resource": "role",
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"status": "active",
"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 |
|---|---|---|---|
name |
string | Yes | minLength: 1 |
description |
string or null | Yes | |
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))$ |
etag |
string | Yes | minLength: 1 |
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)$ |
permissions |
string[] | Yes | |
platform_managed |
boolean | Yes | |
resource |
"role" | Yes | |
scope_ref |
string or null | Yes | |
status |
"active" / "retired" | Yes | |
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.description
At least one alternative must match.
application/json body.description: alternative 1
Type: string.
application/json body.description: alternative 2
Type: null.
application/json body.permissions
Type: string[].
application/json body.permissions item
Type: string. pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$; minLength: 1
application/json body.scope_ref
At least one alternative must match.
application/json body.scope_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.scope_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 |
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 412 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.