# Add administrators

Source: https://docs.settlemint.com/docs/developers/platform-setup/add-admins
Grant DALP platform administrator roles through the API when provisioning operators, compliance teams, auditors, or automation accounts.



Grant platform administrator roles to wallet addresses with the Platform API. Use the API path for automation, bulk operations, or provisioning workflows.

Adding administrators gives selected wallets access to platform-wide operating surfaces before they create API keys or manage assets.

<Mermaid
  chart="`
flowchart TD
Operator[&#x22;Current administrator&#x22;] --> AccessAPI[&#x22;Access manager API&#x22;]
AccessAPI --> Wallet[&#x22;Target wallet address&#x22;]
AccessAPI --> Grants[&#x22;Platform role grants&#x22;]
Grants --> Settings[&#x22;Platform Settings&#x22;]
Grants --> Users[&#x22;User and identity management&#x22;]
Grants --> Providers[&#x22;Compliance and provider configuration&#x22;]
Grants --> Operations[&#x22;System operations and monitoring&#x22;]
`"
/>

For the web interface approach, see the [user guide](/docs/operators/platform-setup/add-admins). Both paths write the same on-chain role record.

## Prerequisites [#prerequisites]

Gather the following before you begin.

* Platform URL
* API key with `admin` system role
* Wallet verification (pincode or 2FA)
* Target wallet address or email

For API key setup, see [Getting Started](/docs/api-reference/reference/getting-started).

## When to add administrators via API [#when-to-add-administrators-via-api]

Use the API to automate initial setup or bulk-provision multiple admins in a single script. You can also integrate role grants into HR and identity provisioning workflows.

<Callout type="info" title="Platform vs Asset roles">
  Platform administrator roles control system-wide operations. The platform
  assigns asset-specific roles (Asset Operator, Custodian, Supply Management,
  Emergency) per token during asset creation.
</Callout>

<Callout type="info" title="Under single sign-on, admin comes from the provider claim">
  When the deployment uses an external OIDC provider, the provider's admin claim
  controls platform admin access and the platform re-derives it on every login,
  bypassing this API path. See [SSO sign-in (OIDC)](/docs/developers/sso-oidc).
</Callout>

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

Each role grants a distinct set of platform capabilities. 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         |

## Steps to add administrators [#steps-to-add-administrators]

<Steps>
  <Step>
    ### Identify target user [#identify-target-user]

    Look up the user by email to get their wallet address. If you already have the wallet address, skip this step. The platform returns the on-chain wallet tied to that account:

    ```bash
    curl -X GET "https://your-platform.example.com/api/user/search?query=new.admin@example.com" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

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

    Save the `wallet` address for the grant step. If the user is not found, verify the email exists on the platform before proceeding.
  </Step>

  <Step>
    ### Check existing roles (optional) [#check-existing-roles-optional]

    Before granting roles, verify the user's current assignments. Checking first prevents duplicate-role errors and confirms the target account is correct. The platform returns all accounts and their current roles:

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

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

    To check a single wallet, pass its address as a path segment:

    ```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 administrator role [#grant-administrator-role]

    Assign the desired platform role to the target wallet. The platform returns the wallet and the granted role on success.

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

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

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

    To assign multiple roles in a single transaction, pass an array for the `role` field.

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

    <Callout type="warning" title="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.
    </Callout>
  </Step>

  <Step>
    ### Verify role assignment [#verify-role-assignment]

    Confirm the grant succeeded by checking the updated roles list. The target wallet now appears with its assigned roles in the response. Confirm the correct roles appear before logging the change.

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

    ![User profile with administrative role assignment](/docs/screenshots/identity/user.webp)
  </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 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 [#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]

A successful grant returns the wallet addresses and roles affected by the operation. Use the response to confirm which accounts and roles the platform wrote on-chain.

| Field      | Type  | Description                          |
| ---------- | ----- | ------------------------------------ |
| `accounts` | array | Wallet addresses that received roles |
| `roles`    | array | Roles that were granted              |

## Best practices [#best-practices]

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

### Role assignment principles [#role-assignment-principles]

Grant only the permissions each account needs. Divide critical functions among different admins to enforce separation of duties. Review assignments periodically and record the reason for each grant. Keeping a clear record makes audits faster and access reviews more accurate.

### Security considerations [#security-considerations]

Limit exposure from a compromised account.

* Restrict `admin` to platform ops accounts
* Use separate wallets per function
* Rotate API keys regularly
* Store credentials in environment variables
* Test role changes in staging first

## Troubleshooting [#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.                  |

## Related guides [#related-guides]

* [Change Admin Roles](/docs/developers/platform-setup/change-admin-roles): Modify or revoke existing role assignments via API
* [API Reference](/docs/api-reference/reference/openapi): Full OpenAPI specification
* [Getting Started](/docs/api-reference/reference/getting-started): API key setup
* [Add Administrators (User Guide)](/docs/operators/platform-setup/add-admins): Web interface approach
* [Platform Setup Overview](/docs/operators/platform-setup/platform-overview): Complete role descriptions and permissions