Manage token roles

QRC token templates expose role-based access control for privileged actions. Common roles include OWNER, ADMIN, MINTER, BURNER, PAUSER, FREEZER, COMPLIANCE_OPERATOR, and TRANSFER_AGENT. The exact set is reported by GET /v1/token-templates/{templateId} and surfaced on the deployed token at GET /v1/tokens/{tokenId}/roles.

`GET /v1/tokens/{tokenId}/roles`

List role assignments on a deployed token.

Aspect	Detail
Method	`GET`
Path	`/v1/tokens/{tokenId}/roles`
Authentication	Bearer API key
Required permissions	`tokens:read`
Approval policy	Not applicable
Blockchain effect	None
Webhook events	None

Example response

{
  "tokenId": "token_abc123",
  "roles": [
    { "role": "ADMIN",  "holders": ["0xabc…"] },
    { "role": "MINTER", "holders": ["0xabc…", "0xdef…"] },
    { "role": "BURNER", "holders": ["0xabc…"] },
    { "role": "PAUSER", "holders": ["0xabc…"] }
  ]
}

`POST /v1/tokens/{tokenId}/roles/grant`

Grant an on-chain role to an address, registered wallet, or vault account.

Aspect	Detail
Required permissions	`tokens:roles:grant` plus the on-chain `ADMIN` role
Idempotency	`Idempotency-Key` header required
Approval policy	Required — role changes are privileged
Blockchain effect	Contract call to `grantRole(role,account)`
Webhook events	`token.role_granted`, `token.operation_failed`

Request body

{
  "role": "MINTER",
  "subject": { "type": "address", "address": "0x9a8e5e21f0c27d2c5c14b6e9bd8e4a0f9c9b4d12" },
  "idempotencyKey": "grant-minter-2026-04-27-001"
}

Response (202)

{
  "operationId": "op_role_grant_321",
  "tokenId": "token_abc123",
  "operationType": "GRANT_ROLE",
  "status": "PENDING_AUTHORIZATION",
  "role": "MINTER",
  "subjectAddress": "0x9a8e5e21…",
  "transactionRequestId": "txreq_005",
  "createdAt": "2026-04-27T10:14:00Z"
}

`POST /v1/tokens/{tokenId}/roles/revoke`

Revoke a role. Same shape as grant and same approval semantics. Webhook events: token.role_revoked, token.operation_failed.

Errors

Code	Type	Meaning
1703	`TOKEN_NOT_DEPLOYED`	Token has no on-chain `contractAddress`.
1708	`TOKEN_ROLE_REQUIRED`	Subject does not currently hold the role to be revoked, or caller lacks the on-chain `ADMIN` role.
1704	`TOKEN_OPERATION_NOT_ALLOWED`	Standard or template does not expose role management.
1200	`POLICY_DENIED`	Approval policy denied the operation.
1201	`APPROVAL_REQUIRED`	Approval is required and was not yet granted.

Transfer tokens Pause, unpause, freeze, unfreeze

Overview

Health

Tenants

Vaults

Wallets

Transactions

Assets

Tokens

Webhooks

Administration

Manage token roles

`GET /v1/tokens/{tokenId}/roles`

Example response

`POST /v1/tokens/{tokenId}/roles/grant`

Request body

Response (202)

`POST /v1/tokens/{tokenId}/roles/revoke`

Errors

​GET /v1/tokens/{tokenId}/roles

​Example response

​POST /v1/tokens/{tokenId}/roles/grant

​Request body

​Response (202)

​POST /v1/tokens/{tokenId}/roles/revoke

​Errors

​Related

`GET /v1/tokens/{tokenId}/roles`

Example response

`POST /v1/tokens/{tokenId}/roles/grant`

Request body

Response (202)

`POST /v1/tokens/{tokenId}/roles/revoke`

Errors

Related