Manage asset-level admin roles on DALP via API

This guide explains how to programmatically modify administrator roles for specific assets using the DALP API. Use these endpoints to grant or revoke asset-level permissions for managing individual assets.

For the web interface approach, see the user guide.

Prerequisites

Platform URL (e.g., 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 method enabled on your account (e.g., pincode or 2FA)
Asset contract address of the asset to modify

When to change asset admin roles

Common scenarios

Initial deployment — Assign operators after asset creation
Role expansion — Operator taking on additional responsibilities
Role reduction — Removing permissions no longer needed
Team changes — Transferring responsibilities between operators
Automation — Integrating role management into provisioning workflows

Security considerations

Follow principle of least privilege
Remove roles when no longer needed
Document role changes for compliance
Coordinate with affected operators

About asset admin roles

Each asset has its own set of administrators with specific roles:

Role	Description	Common use cases
`admin`	Permission management for the asset	Manage other administrators' roles and permissions
`custodian`	Freeze addresses, force transfers, and asset recovery	Custody/operations teams handling interventions
`emergency`	Pause/unpause and ERC20 recovery actions	Incident response team, post-deploy unpausing
`governance`	Asset policy, verification, and compliance settings	Team tuning compliance modules or governance parameters
`supplyManagement`	Mint and burn permissions via `/api/token/:address/mint`	Operators issuing, redeeming, or retiring supply

Asset vs platform roles

Asset roles are specific to individual assets. Each asset has its own access control. Platform system roles (like tokenManager) control platform-wide capabilities. See Change Admin Roles for system roles.

Changing roles

Get asset details

Query the asset to review current role assignments:

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

Asset address in path

The asset contract address is part of the URL path: /api/token/{assetAddress}

Response (relevant fields):

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

Review the accessControl field to see current role assignments. Each role contains an array of accounts with that role.

Grant a role

Grant one or more roles to a wallet address on the asset:

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" }
  }'

Response:

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

Grant multiple roles

Assign multiple roles to one wallet in a single transaction:

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" }
  }'

Batch grant to multiple wallets

Grant the same role to multiple wallets efficiently:

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" }
  }'

Batch limitations

You cannot grant multiple roles to multiple addresses in a single transaction. Use separate requests for each address or each role combination.

Revoke a role

Remove one or more roles from a wallet address:

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" }
  }'

Response:

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

Revoke multiple roles

Remove multiple roles from one wallet in a single transaction:

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" }
  }'

Batch revoke from multiple wallets

Revoke the same role from multiple wallets efficiently:

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" }
  }'

Verify changes

Confirm role changes by fetching updated asset details:

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

The response shows all current role assignments in the accessControl field. Verify the changes were applied correctly.

Request parameters

Parameter	Type	Required	Description
`account`	string	Yes*	Single wallet address for role assignment
`accounts`	string[]	Yes*	Multiple wallet addresses (alternative to `account`)
`role`	string	Yes*	Single role to grant/revoke (use with `accounts`)
`roles`	string[]	Yes*	Multiple roles to grant/revoke (use with `account`)
`walletVerification`	object	Yes	Your wallet verification to authorize the blockchain transaction

*Use either account + roles OR accounts + role

Wallet verification object

Field	Type	Description
`secretVerificationCode`	string	6-digit pincode or TOTP code
`verificationType`	string	"PINCODE" (default), "SECRET_CODES", or "OTP"

Response fields

Field	Type	Description
`accounts`	array	Wallet addresses that were modified

Best practices

Role assignment

Principle of least privilege — Grant only necessary roles
Separation of duties — Divide critical functions among multiple administrators
Regular review — Audit role assignments when responsibilities change
Documentation — Record role changes and business rationale

Security

Limit the admin role to trusted individuals
Separate operational roles from governance roles
Maintain backup administrators for critical roles
Use different wallets for different administrative functions

Operations

Assign Supply Management to asset operators who mint/burn
Give Emergency role to operations team for incident response
Separate Custodian role for transfer management and compliance
Reserve Governance for strategic configuration decisions

Troubleshooting

Issue	Solution
Permission denied	Verify you have the `admin` role on this specific asset.
Asset not found	Check the asset contract address is correct. Ensure the asset is deployed on this platform.
Role not found	Check the role name matches exactly (case-sensitive). Valid roles: admin, custodian, emergency, governance, supplyManagement.
Transaction fails	Ensure wallet has sufficient gas. Verify PIN/OTP is correct. Check network connectivity.
Changes not visible	Wait for blockchain confirmation. Refresh asset details. Check transaction was successful.
Cannot revoke own role	Have another user with the `admin` role to revoke your role if needed.

Change Admin Roles — Manage platform-level system roles

Change asset admin roles