Skip to main content
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.
AspectDetail
MethodGET
Path/v1/tokens/{tokenId}/roles
AuthenticationBearer API key
Required permissionstokens:read
Approval policyNot applicable
Blockchain effectNone
Webhook eventsNone

​
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.
AspectDetail
Required permissionstokens:roles:grant plus the on-chain ADMIN role
IdempotencyIdempotency-Key header required
Approval policyRequired — role changes are privileged
Blockchain effectContract call to grantRole(role,account)
Webhook eventstoken.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

CodeTypeMeaning
1703TOKEN_NOT_DEPLOYEDToken has no on-chain contractAddress.
1708TOKEN_ROLE_REQUIREDSubject does not currently hold the role to be revoked, or caller lacks the on-chain ADMIN role.
1704TOKEN_OPERATION_NOT_ALLOWEDStandard or template does not expose role management.
1200POLICY_DENIEDApproval policy denied the operation.
1201APPROVAL_REQUIREDApproval is required and was not yet granted.