# Change admin roles

Source: https://docs.settlemint.com/docs/developer-guides/platform-setup/change-admin-roles
Update platform administrator role assignments through the API when operating responsibilities, least-privilege reviews, or provisioning workflows change.



Platform administrator roles control who can manage system configuration, identities, compliance settings, token creation, feeds, gas sponsorship, and audit visibility. Use the access manager API when role changes must be automated, reviewed, or coordinated with provisioning workflows.

Platform administrator role changes update who can operate DALP setup, compliance, identity, infrastructure, and evidence surfaces.

<Mermaid
  chart="`
flowchart TD
Provisioning[&#x22;Provisioning workflow or operator&#x22;] --> AccessAPI[&#x22;Access manager API&#x22;]
AccessAPI --> User[&#x22;Target user or wallet&#x22;]
AccessAPI --> Roles[&#x22;Platform administrator roles&#x22;]
Roles --> Identity[&#x22;Identity and user controls&#x22;]
Roles --> Compliance[&#x22;Compliance and provider controls&#x22;]
Roles --> Infrastructure[&#x22;System, gas, and addon controls&#x22;]
Roles --> Evidence[&#x22;Monitoring and evidence views&#x22;]
`"
/>

For the web interface approach, see the [user guide](/docs/user-guides/platform-setup/change-admin-roles).

## Prerequisites [#prerequisites]

* Platform URL (e.g., `https://your-platform.example.com`)
* API key from a user with the **Admin** role (see [Getting Started](/docs/developer-guides/api-integration/getting-started) for API key setup)
* Wallet verification method enabled on your account (e.g., pincode or 2FA)

## When to change admin roles [#when-to-change-admin-roles]

### Common scenarios [#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 [#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 [#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                   |
| `auditor`            | Read-only inspection of operational and security-sensitive surfaces     | Audit users who need visibility without operator rights   |
| `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          |
| `feedsManager`       | Feed registration, updates, and removal                                 | Teams operating pricing or market data feeds              |
| `gasManager`         | Paymaster funding and sponsorship configuration                         | Teams operating account abstraction gas sponsorship       |

## Changing roles [#changing-roles]

<Steps>
  <Step>
    ### List current roles [#list-current-roles]

    Check existing role assignments before making changes:

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

    **Response:**

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

    Add `?excludeContracts=true` when you only want externally owned accounts in the list.

    To check roles for a specific wallet:

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

  <Step>
    ### Grant a role [#grant-a-role]

    Grant a single system role to a wallet address:

    ```bash
    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:**

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

    #### Grant multiple roles [#grant-multiple-roles]

    Assign multiple roles to one wallet in a single transaction:

    ```bash
    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 [#batch-grant-to-multiple-wallets]

    Grant the same role to multiple wallets efficiently:

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

    <Callout type="warning" title="Batch limitations">
      You cannot grant multiple roles to multiple addresses in a single transaction. Use separate requests for each address
      or each role combination.
    </Callout>
  </Step>

  <Step>
    ### Revoke a role [#revoke-a-role]

    Remove a system role from a wallet address:

    ```bash
    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:**

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

    #### Revoke multiple roles [#revoke-multiple-roles]

    Remove multiple roles from one wallet in a single transaction:

    ```bash
    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 [#batch-revoke-from-multiple-wallets]

    Revoke the same role from multiple wallets efficiently:

    ```bash
    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" }
      }'
    ```
  </Step>

  <Step>
    ### Verify changes [#verify-changes]

    Confirm role changes by listing updated roles:

    ```bash
    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.
  </Step>
</Steps>

## Request parameters [#request-parameters]

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

### Wallet verification object [#wallet-verification-object]

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

## Response fields [#response-fields]

| Field      | Type  | Description                         |
| ---------- | ----- | ----------------------------------- |
| `accounts` | array | Wallet addresses that were modified |
| `roles`    | array | Roles that were granted/revoked     |

## Role dependencies and conflicts [#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 [#best-practices]

### Role assignment [#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 [#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 [#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 [#troubleshooting]

| Issue                   | Solution                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| Permission denied       | Verify you have the `admin` system role. Only admins can grant/revoke roles.                 |
| Role not found          | Check the role name matches exactly (case-sensitive). See available roles table above.       |
| Transaction fails       | Ensure wallet has sufficient gas. Verify PIN/OTP is correct. Check network connectivity.     |
| Duplicate role error    | The wallet already has this role. Check current roles before granting.                       |
| Cannot revoke own admin | Smart contract prevents self-revocation of admin role. Another admin must revoke it.         |
| Batch operation fails   | Cannot grant multiple roles to multiple addresses in one call. Split into separate requests. |

## Related guides [#related-guides]

* [Change Asset Admin Roles](/docs/developer-guides/asset-servicing/change-asset-admin-roles): Manage token-level permissions
* [API Integration](/docs/developer-guides/api-integration/getting-started): Getting started with the DALP API
* [Change Admin Roles (UI)](/docs/user-guides/platform-setup/change-admin-roles): Web interface guide