Change asset admin roles

Asset administrator roles control who can operate one token after issuance. This API guide covers grant and revoke requests for token-level roles only. These requests do not change platform-wide system roles or the asset's ownership model. Use these endpoints when you need repeatable role provisioning for operations teams, custodians, supply managers, governance operators, or emergency responders.

For the web interface approach, see the operator user guide. The sections below cover the API request shape, batch options, and what to verify after each change.

Prerequisites

• Platform URL, such as https://your-platform.example.com
• API key from a user with the admin role on the target asset. See Getting Started for API key setup.
• Wallet verification when the platform requires it for transaction signing, such as pincode, secret code, or OTP.
• Asset contract address for the asset to modify.
• Target wallet address, or addresses, for the role change.

When to change asset admin roles

Common scenarios

• Assign operators after asset creation.
• Give an existing operator another role when their responsibilities expand.
• Remove permissions when an operator no longer needs them.
• Transfer responsibilities between operators after a team change.
• Include role management in provisioning workflows.

Security considerations

• Grant only the roles each operator needs.
• Remove roles when responsibilities end.
• Record the business reason for each role change.
• Coordinate the timing with affected operators.

About asset admin roles

Each asset has its own administrator set. Roles define what each administrator can do on that asset.

Changing roles

curl -X GET "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "id": "0x9459D52E60edBD3178f00F9055f6C117a21b4220",
  "name": "Example Asset",
  "symbol": "EXA",
  "decimals": 18,
  "accessControl": {
    "id": "0x1234567890AbCdEf1234567890AbCdEf12345678",
    "admin": [{ "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }],
    "custodian": [],
    "emergency": [],
    "governance": [{ "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }],
    "supplyManagement": []
  }
}

curl -X POST "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/grant-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": ["supplyManagement"],
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

{
  "accounts": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"]
}

curl -X POST "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/grant-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": ["supplyManagement", "custodian"],
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

curl -X POST "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/grant-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"],
    "role": "supplyManagement",
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

curl -X DELETE "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/revoke-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": ["supplyManagement"],
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

{
  "accounts": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"]
}

curl -X DELETE "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/revoke-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": ["supplyManagement", "custodian"],
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

curl -X DELETE "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220/revoke-role" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"],
    "role": "supplyManagement",
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

curl -X GET "https://your-platform.example.com/api/token/0x9459D52E60edBD3178f00F9055f6C117a21b4220" \
  -H "X-Api-Key: YOUR_API_KEY"

Request parameters

*Each request uses one shape: either account with roles for one account receiving multiple permissions, or accounts with role for multiple accounts receiving one permission. Do not mix the two shapes in a single request.

Wallet verification object

Include walletVerification when your platform requires it for the signing account. The platform supports three verification types.

Response fields

The response contains the wallet addresses that the queued role operation covers. Fetch the asset after blockchain confirmation to check indexed role state.

Operational notes

Send one request shape at a time: accounts with one role, or one account with roles. Mixing the two shapes in a single request is not supported.

The platform deduplicates repeated accounts before queuing the blockchain transaction. Revoke requests for non-admin roles do not affect the asset's permission-management role.

When a request revokes multiple permissions from the caller, the platform processes the admin revoke last, letting the caller complete the remaining changes within the same transaction. The response lists the wallet addresses included in the queued role operation. Fetch the asset again to confirm indexed role state after blockchain confirmation.

Best practices

Role assignment

• Grant only the roles each operator needs.
• Split critical functions across more than one administrator.
• Review role assignments when responsibilities change.
• Record each role change and its business reason.

Security

• Limit the admin role to trusted operators.
• Separate operational roles from governance roles.
• Keep backup administrators for critical roles.
• Use different wallets for different administrative functions.

Operations

• Assign supplyManagement to operators who mint or burn.
• Give emergency to the operations team that handles incidents.
• Use custodian for transfer management and compliance operations.
• Reserve governance for strategic configuration decisions.

Troubleshooting

Related guides

• Change Admin Roles - Manage platform-level system roles