System account roles API reference

An auditor confirming who can mint, an operator checking before a role change, or a security review reconciling privileged access all need the same answer: which accounts hold which system roles right now. The system account roles surface answers by account. It lists every account in the system access-control register with the roles each one holds, and reads the roles for one specific address.

These endpoints read by account. To read role assignments grouped by participant, with signing-address against operations-address comparison and the drift signal, use the participant role assignments API instead. Both surfaces are read-only: they report the current register and never grant or revoke a role.

When to use each surface

This page reads the access-control register account by account, including contract accounts and role holders that are not mapped to a participant. The participant view reads the same roles but organises them by participant identity and adds the drift comparison.

Endpoints

The list endpoint uses the collection envelope with data, meta, and pagination links. The single-account read uses the single-resource envelope with data and links.self. The active organization and system context bound every read, as described in Organization and system scope.

Path parameters

Item fields

Both endpoints return the same per-account shape.

Role names

The endpoint returns every role value stored in the indexed access-control register, not only the operator roles the role-management interface offers for assignment. The full set is:

Module roles and some asset roles appear only when the indexed register includes them for that account. Filter them out with filter[excludeContracts]=true when you only want human-held operator roles.

Read one account

Read the roles held by a single address. The roles array is empty when the account holds none.

curl --request GET \
  "https://your-platform.example.com/api/v2/system/accounts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/roles" \
  --header "X-Api-Key: YOUR_DALP_API_KEY"

Example response:

{
  "data": {
    "account": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "roles": ["admin", "tokenManager"]
  },
  "links": {
    "self": "/v2/system/accounts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/roles"
  }
}

List the register

The list endpoint returns one row per account, with the roles each account holds. The endpoint accepts the standard collection query parameters: pagination with page[offset] and page[limit], sorting with sort, global search with filter[q], and per-field filters. The default sort is by account, which is also the only sortable field.

curl --globoff \
  "https://your-platform.example.com/api/v2/system/accounts/roles?page[limit]=50" \
  --header "X-Api-Key: YOUR_DALP_API_KEY"

Example response:

{
  "data": [
    {
      "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
      "roles": ["admin", "tokenManager"]
    },
    {
      "account": "0x8e5F72f6E5b3B4D1234567890AbCdEf123456789",
      "roles": ["identityManager"]
    }
  ],
  "meta": {
    "total": 2,
    "facets": {
      "roles": [
        { "value": "admin", "count": 1 },
        { "value": "tokenManager", "count": 1 },
        { "value": "identityManager", "count": 1 }
      ]
    }
  },
  "links": {
    "self": "/v2/system/accounts/roles?sort=account&page[offset]=0&page[limit]=50",
    "first": "/v2/system/accounts/roles?sort=account&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/accounts/roles?sort=account&page[offset]=0&page[limit]=50"
  }
}

Find every holder of a role

Filter on roles to list the accounts that hold a specific role. To answer "who can deploy assets", query tokenManager:

curl --globoff \
  "https://your-platform.example.com/api/v2/system/accounts/roles?filter[roles]=tokenManager" \
  --header "X-Api-Key: YOUR_DALP_API_KEY"

The meta.facets block reports the count of accounts holding each role across the unpaginated result, so you can read how privileged access is distributed without making a second call.

Exclude contract accounts

Pass filter[excludeContracts]=true to drop contract accounts from the list and return only externally owned accounts. Use this filter when you are reviewing human-held privileged access and do not want module or registry contracts in the result.

curl --globoff \
  "https://your-platform.example.com/api/v2/system/accounts/roles?filter[excludeContracts]=true" \
  --header "X-Api-Key: YOUR_DALP_API_KEY"

Search the register

Global search matches against the account address and role names. To find an address by a known prefix:

curl --globoff \
  "https://your-platform.example.com/api/v2/system/accounts/roles?filter[q]=0x742d35" \
  --header "X-Api-Key: YOUR_DALP_API_KEY"

Authorization

Reading the register requires a caller with system access to the active organization and system. Authenticate server integrations with the X-Api-Key header shown in the examples; browser or RPC integrations can use an authenticated user session through the standard cookie or authorization flow. The reads report the register as indexed and do not require any role-management permission to change it.

Related

• Participant role assignments
• Role-based access control
• Authorization
• Organization and system scope
• Request headers