# Add administrators

Source: https://docs.settlemint.com/docs/developer-guides/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 DALP 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/user-guides/platform-setup/add-admins).

## Prerequisites [#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](/docs/developer-guides/api-integration/getting-started) for API key setup

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

### Recommended scenarios [#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

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

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

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

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

    **Response:**

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

    Save the `wallet` address for the grant step.
  </Step>

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

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

    ```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": []
      },
      {
        "account": "0xExistingAdmin...",
        "roles": ["admin", "tokenManager"]
      }
    ]
    ```

    To check a single wallet directly:

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

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

    **Response:**

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

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

    To assign multiple roles 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": ["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 role was granted by checking the updated roles list:

    ```bash
    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](/docs/screenshots/identity/user.webp)
  </Step>
</Steps>

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

## Best practices [#best-practices]

### Role assignment principles [#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 [#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 [#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/developer-guides/platform-setup/change-admin-roles): Modify or revoke existing role assignments via API
* [API Reference](/docs/developer-guides/api-integration/api-reference): Full OpenAPI specification
* [Getting Started](/docs/developer-guides/api-integration/getting-started): API key setup
* [Add Administrators (User Guide)](/docs/user-guides/platform-setup/add-admins): Web interface approach
* [Platform Setup Overview](/docs/user-guides/platform-setup/platform-overview): Complete role descriptions and permissions