# Change admin roles

Source: https://docs.settlemint.com/docs/developers/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. Role updates take effect on-chain immediately: the affected wallet gains or loses capabilities for every subsequent operation.

<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/operators/platform-setup/change-admin-roles). Both paths write the same on-chain role record.

## Prerequisites [#prerequisites]

You need a platform URL, an API key with the Admin role, and wallet verification enabled (pincode or 2FA). For API key setup, see [Getting Started](/docs/api-reference/reference/getting-started).

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

### Common scenarios [#common-scenarios]

Use the access manager API to add permissions after initial platform setup, adjust roles when responsibilities shift, or remove permissions to follow least privilege. Use it also to grant temporary access for a specific task or to integrate role management into a provisioning workflow.

### Security considerations [#security-considerations]

Follow the principle of least privilege. Remove roles when they are no longer needed. Record role changes for audit purposes and coordinate updates with affected admins.

## Available system roles [#available-system-roles]

Grant only the roles each account needs.

| 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 advanced accounts gas sponsorship         |

## Changing roles [#changing-roles]

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

    Check existing role assignments before making changes. This prevents duplicate-role errors and confirms the target account is correct:

    ```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. This filters out smart-contract accounts and returns only externally owned accounts.

    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. The platform writes the role on-chain and the change takes effect immediately.

    ```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]

    To assign multiple roles to one wallet, pass an array for the `role` field. The platform writes all roles in one on-chain 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]

    To grant the same role to multiple wallets, pass an array for the `account` field. Use separate requests when you need different roles per wallet.

    ```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. The platform removes the role on-chain immediately. The affected wallet loses the capability for all subsequent operations.

    ```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]

    To remove multiple roles from one wallet, pass an array for the `role` field. The platform removes all listed roles in one on-chain 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]

    To revoke the same role from multiple wallets, pass an array for the `account` field. Use separate requests when you need different roles per wallet.

    ```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]

All three parameters are required.

| 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]

The `walletVerification` object authorizes the on-chain transaction. Pass the code that matches your account's configured method. The platform rejects the request if the code is missing or incorrect.

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

## Response fields [#response-fields]

Both grant and revoke operations return the wallet addresses and roles affected by the operation. Use the response to confirm which accounts and roles the platform wrote or removed on-chain.

| 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]

Some functions require multiple roles working together. The combinations below represent the minimum set needed for each operating function. Grant the full combination, not just one role:

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

## Best practices [#best-practices]

Apply these practices before changing roles in a production environment. They reduce the blast radius of a compromised account and make periodic access reviews easier to complete.

### Role assignment [#role-assignment]

Grant only the permissions each account needs. Divide critical functions among multiple admins to enforce separation of duties. Review and update role assignments periodically and record the reason for each change. A clear record makes audits faster and reduces ambiguity during access reviews.

### Security [#security]

Limit exposure from a compromised account.

* Restrict `admin` to platform ops accounts
* Use separate wallets per function
* Keep backup administrators for critical roles
* Monitor role changes through event logs

### Operations [#operations]

Coordinate live role changes with these practices.

* 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/developers/asset-servicing/change-asset-admin-roles): Manage token-level permissions
* [API Integration](/docs/api-reference/reference/getting-started): Getting started with the Platform API
* [Change Admin Roles (UI)](/docs/operators/platform-setup/change-admin-roles): Web interface guide