SettleMint
Developer guidesPlatform setup

Change admin roles

Grant or revoke platform administrator roles.

This guide explains how to modify platform administrator roles using the API. Use this for automation, organizational restructuring, 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 key from a user with the Admin role (see Getting Started for API key setup)
  • Wallet verification method enabled on your account (e.g., pincode or 2FA)

When to change admin roles

Common scenarios

  • Initial setup — First admin needs additional roles after platform initialization
  • Role expansion — Admin taking on new responsibilities
  • Role reduction — Removing unnecessary permissions following least privilege
  • Temporary delegation — Granting time-limited permissions for specific tasks
  • Organizational changes — Restructuring administrative responsibilities
  • Automation — Integrating role management into your provisioning workflows

Security considerations

  • Follow principle of least privilege
  • Remove roles when no longer needed
  • Document role changes for audit purposes
  • Coordinate with affected administrators

Available system roles

RoleDescriptionCommon use cases
adminRoot authority that can grant or revoke all other system rolesPlatform ops account, initial setup
systemManagerCore system configuration (upgrades, registering factories/modules)Deployment team, rarely granted to EOAs
identityManagerIdentity registry maintenance (register/recover identities, onboarding)Compliance/onboarding teams managing identities
tokenManagerToken factory calls such as /api/token/createEvery wallet that deploys assets
complianceManagerGlobal compliance module setup, bypass lists, enforcement togglesCustom compliance flows, allowlists
claimPolicyManagerTrusted issuer and claim topic managementWorkflows that check collateral/KYC claims before minting
claimIssuerPermission to create claims on identitiesAuditors, service providers issuing attestations

Changing roles

List current roles

Check existing role assignments before making changes:

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

Response:

[
  {
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "roles": ["admin", "tokenManager"]
  },
  {
    "account": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
    "roles": ["identityManager"]
  }
]

To check roles for a specific wallet:

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

Grant a role

Grant a single system role to a wallet address:

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": "tokenManager",
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

Response:

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

Grant multiple roles

Assign multiple roles to one wallet 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": ["tokenManager", "identityManager"],
    "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/system/access-manager/grant-roles" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"],
    "role": "tokenManager",
    "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 a system role from a wallet address:

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

Response:

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

Revoke multiple roles

Remove multiple roles from one wallet in a single transaction:

curl -X DELETE "https://your-platform.example.com/api/system/access-manager/revoke-roles" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "role": ["tokenManager", "identityManager"],
    "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/system/access-manager/revoke-roles" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"],
    "role": "tokenManager",
    "walletVerification": { "secretVerificationCode": "YOUR_PINCODE" }
  }'

Verify changes

Confirm role changes by listing updated roles:

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

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

Request parameters

ParameterTypeRequiredDescription
accountstring or arrayYesWallet address(es) to grant/revoke role
rolestring or arrayYesRole(s) to grant/revoke
walletVerificationobjectYesYour wallet verification to authorize the blockchain transaction

Wallet verification object

FieldTypeDescription
secretVerificationCodestring6-digit pincode or TOTP code
verificationTypestring"PINCODE" (default), "SECRET_CODES", or "OTP"

Response fields

FieldTypeDescription
accountsarrayWallet addresses that were modified
rolesarrayRoles that were granted/revoked

Role dependencies and conflicts

Common role combinations for specific functions:

  • Compliance Manager + Identity Manager — Complete compliance setup
  • Token Manager — Full token lifecycle management
  • Identity Manager + Claim Issuer — Complete user onboarding

Best practices

Role assignment

  • Principle of least privilege — Grant only necessary permissions
  • Separation of duties — Divide critical functions among multiple admins
  • Regular review — Audit and update roles periodically
  • Documentation — Record role changes and rationale

Security

  • Keep admin role restricted to platform ops accounts
  • Use separate wallets for different administrative functions
  • Maintain backup administrators for critical roles
  • Monitor role changes through event logs

Operations

  • Test role changes in a staging environment first
  • Coordinate role changes with affected administrators
  • Plan for administrator unavailability with backup coverage
  • Define clear escalation paths for requesting permissions

Troubleshooting

IssueSolution
Permission deniedVerify you have the admin system role. Only admins can grant/revoke roles.
Role not foundCheck the role name matches exactly (case-sensitive). See available roles table above.
Transaction failsEnsure wallet has sufficient gas. Verify PIN/OTP is correct. Check network connectivity.
Duplicate role errorThe wallet already has this role. Check current roles before granting.
Cannot revoke own adminSmart contract prevents self-revocation of admin role. Another admin must revoke it.
Batch operation failsCannot grant multiple roles to multiple addresses in one call. Split into separate requests.

Add administrators

Grant administrative permissions to users in your organization via API.

Create users

Create platform users with automatic wallet and identity setup. Includes workflows for passive token holders and active users with API keys.

On this page

PrerequisitesWhen to change admin rolesCommon scenariosSecurity considerationsAvailable system rolesChanging rolesList current rolesGrant a roleGrant multiple rolesBatch grant to multiple walletsRevoke a roleRevoke multiple rolesBatch revoke from multiple walletsVerify changesRequest parametersWallet verification objectResponse fieldsRole dependencies and conflictsBest practicesRole assignmentSecurityOperationsTroubleshootingRelated guides