Add platform administrators via the DALP API

This guide explains how to grant platform administrator roles to wallet addresses using the API. Use this for automation, bulk operations, or integration into your provisioning workflows.

For the web interface approach, see the user guide.

Prerequisites

Platform URL (e.g., https://your-platform.example.com)
API access token with admin system role (required to grant platform administrator roles)
Wallet verification method enabled on your account (e.g., pincode or 2FA)
Target wallet address (can be any valid address or looked up by email)
See Getting Started for API key setup

When to add administrators via API

Recommended scenarios

Initial setup automation — Scripting first-time platform configuration
Bulk provisioning — Adding multiple administrators in batch operations
Organizational onboarding — Integrating with HR/identity systems

Platform vs Asset roles

Platform administrator roles control system-wide operations. Asset-specific roles (Asset Operator, Custodian, Supply Management, Emergency) are assigned per token during asset creation.

Available system roles

Role	Description	Common use cases
`admin`	Root authority that can grant or revoke all other system roles	Platform ops account, initial setup
`systemManager`	Core system configuration (upgrades, registering factories/modules)	Deployment team, rarely granted to EOAs
`identityManager`	Identity registry maintenance (register/recover identities, onboarding)	Compliance/onboarding teams managing identities
`tokenManager`	Token factory calls such as `/api/token/create`	Every wallet that deploys assets
`complianceManager`	Global compliance module setup, bypass lists, enforcement toggles	Custom compliance flows, allowlists
`claimPolicyManager`	Trusted issuer and claim topic management	Workflows that check collateral/KYC claims before minting
`claimIssuer`	Permission to create claims on identities	Auditors, service providers issuing attestations

Steps to add administrators

Identify target user

Look up the user by email to get their wallet address. If you already have the wallet address, skip this step.

curl -X GET "https://your-platform.example.com/api/user/[email protected]" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

[
  {
    "id": "usr_abc123",
    "name": "New Admin",
    "wallet": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "role": "member"
  }
]

Save the wallet address for the grant step.

Check existing roles (optional)

Before granting roles, verify the user's current role assignments:

curl -X GET "https://your-platform.example.com/api/system/access-manager/roles" \
  -H "X-Api-Key: YOUR_API_KEY"

Response:

[
  {
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": []
  },
  {
    "account": "0xExistingAdmin...",
    "roles": ["admin", "tokenManager"]
  }
]

To check a single wallet directly:

curl -X GET "https://your-platform.example.com/api/system/access-manager/roles/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
  -H "X-Api-Key: YOUR_API_KEY"

Grant administrator role

Assign the desired platform role to the target wallet:

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

Response:

{
  "accounts": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
  "roles": ["identityManager"]
}

Grant multiple roles

To assign multiple roles in a single transaction:

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

Batch limitations

You can grant multiple roles to one address, or one role to multiple addresses, but not multiple roles to multiple addresses in a single request. Use separate requests for complex bulk operations.

Verify role assignment

Confirm the role was granted by checking the updated roles list:

curl -X GET "https://your-platform.example.com/api/system/access-manager/roles" \
  -H "X-Api-Key: YOUR_API_KEY"

The target wallet should now appear with the assigned roles in the response.

User profile with administrative role assignment

Request parameters

Parameter	Type	Required	Description
`account`	string or array	Yes	Wallet address(es) to grant role to
`role`	string or array	Yes	Role(s) to grant
`walletVerification`	object	Yes	Your wallet verification to authorize the blockchain transaction

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 received roles
`roles`	array	Roles that were granted

Best practices

Role assignment principles

Least privilege — Grant only necessary permissions
Separation of duties — Divide critical functions among different admins
Regular review — Audit role assignments periodically
Document decisions — Record why roles were granted for audit purposes

Security considerations

Keep admin role restricted to platform ops accounts
Use separate wallets for different administrative functions
Store API keys securely and rotate regularly
Use environment variables for credentials in scripts
Test role changes in staging before production

Troubleshooting

Issue	Solution
`401 Unauthorized`	API key is invalid, expired, or disabled
`403 USER_NOT_AUTHORIZED`	Verify you have `admin` system role. Only admins can grant other system roles.
`404 User not found`	Email lookup failed; verify user exists or use wallet address directly
`400 Role not found`	Check role name matches exactly (case-sensitive). See available roles table above.
`400 Duplicate role`	User already has this role. Check existing roles before granting.
Transaction fails	Ensure your wallet has sufficient gas. Verify PIN/OTP is correct.
Batch operation fails	Cannot grant multiple roles to multiple addresses in one call. Split into separate requests.
User cannot see new permissions	Ask user to log out and back in. Verify transaction was confirmed on-chain.

Change Admin Roles — Modify or revoke existing role assignments via API
API Reference — Full OpenAPI specification
Getting Started — API key setup
Add Administrators (User Guide) — Web interface approach
Platform Setup Overview — Complete role descriptions and permissions

Add administrators

Prerequisites

When to add administrators via API

Recommended scenarios

Available system roles

Steps to add administrators

Identify target user

Check existing roles (optional)

Grant administrator role

Grant multiple roles

Verify role assignment

Request parameters

Wallet verification object

Response fields

Best practices

Role assignment principles

Security considerations

Troubleshooting

On this page