> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quantumapi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage token roles

> Inspect, grant, and revoke on-chain roles such as MINTER, BURNER, PAUSER, and COMPLIANCE_OPERATOR.

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

```json theme={null}
{
  "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

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

### Response (202)

```json theme={null}
{
  "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.                                                      |

## Related

* [Pause and freeze](/api-reference/tokens/pause-and-freeze)
* [Compliance and allowlist](/api-reference/tokens/compliance-and-allowlist)
* [Security model](/qustody/token-management/security-model)