# System account roles API reference Source: https://docs.settlemint.com/docs/api-reference/reference/system-account-roles Read the system access-control register through the DALP Platform API, listing every account and the roles it holds and reading the roles for a single account address. 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](/docs/api-reference/reference/participant-role-assignments) instead. Both surfaces are read-only: they report the current register and never grant or revoke a role. ## When to use each surface [#when-to-use-each-surface] | Question | Surface | | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Which accounts hold a given system role, across the whole deployment? | System account roles (this page) | | Which roles does this one address hold? | System account roles (this page) | | Which roles does each participant hold, split by signing and operations address? | [Participant role assignments](/docs/api-reference/reference/participant-role-assignments) | | Does a participant hold a role on the signing address that the operations address is missing? | [Participant role assignments](/docs/api-reference/reference/participant-role-assignments) | 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 [#endpoints] | Endpoint | Use it for | | --------------------------------------------- | ----------------------------------------------------------- | | `GET /api/v2/system/accounts/roles` | List every account in the register with the roles it holds. | | `GET /api/v2/system/accounts/{address}/roles` | Read the roles held by one account. | 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](/docs/api-reference/reference/organization-system-scope). ## Path parameters [#path-parameters] | Parameter | Type | Description | | --------- | ----------- | ------------------------------------------------------------------ | | `address` | EVM address | Single-account read only. The account whose roles the query reads. | ## Item fields [#item-fields] Both endpoints return the same per-account shape. | Field | Type | Description | | --------- | ------------------- | ---------------------------- | | `account` | EVM address | The account address. | | `roles` | array of role names | The roles the account holds. | ## Role names [#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: | Role | Grants | | ---------------------------------- | ------------------------------------------------------------------------------------- | | `admin` | Full administrative control of the system, including managing other roles. | | `systemManager` | System-level configuration and management. | | `tokenManager` | Deploying assets through the token factory. | | `complianceManager` | Compliance module setup, bypass lists, and enforcement toggles. | | `claimPolicyManager` | Trusted issuer and claim topic management. | | `claimIssuer` | Issuing claims on identities. | | `identityManager` | Identity registry maintenance, including registration and recovery. | | `feedsManager` | Registering, updating, and removing pricing or market-data feeds. | | `gasManager` | Funding and configuring sponsored-gas for advanced accounts. | | `auditor` | Read access for review and reporting. | | `systemModule` | Platform system module contracts. | | `tokenFactoryModule` | Token factory module contracts. | | `identityRegistryModule` | Identity registry module contracts. | | `tokenFactoryRegistryModule` | Token factory registry module contracts. | | `trustedIssuersMetaRegistryModule` | Trusted issuers meta-registry module contracts. | | `addonModule` | Addon module contracts. | | `addonRegistryModule` | Addon registry module contracts. | | `custodian` | Asset-level custodian role (visible when the account also holds asset roles). | | `emergency` | Asset-level emergency role (visible when the account also holds asset roles). | | `fundsManager` | Asset-level funds manager role (visible when the account also holds asset roles). | | `governance` | Asset-level governance role (visible when the account also holds asset roles). | | `saleAdmin` | Asset-level sale admin role (visible when the account also holds asset roles). | | `supplyManagement` | Asset-level supply management role (visible when the account also holds asset roles). | | `organisationIdentityManager` | Organisation identity manager role. | 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-one-account] Read the roles held by a single address. The roles array is empty when the account holds none. ```bash curl --request GET \ "https://your-platform.example.com/api/v2/system/accounts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/roles" \ --header "X-Api-Key: YOUR_DALP_API_KEY" ``` Example response: ```json { "data": { "account": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F", "roles": ["admin", "tokenManager"] }, "links": { "self": "/v2/system/accounts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F/roles" } } ``` ## List the register [#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. ```bash 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: ```json { "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 [#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`: ```bash 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 [#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. ```bash 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 [#search-the-register] Global search matches against the account address and role names. To find an address by a known prefix: ```bash curl --globoff \ "https://your-platform.example.com/api/v2/system/accounts/roles?filter[q]=0x742d35" \ --header "X-Api-Key: YOUR_DALP_API_KEY" ``` ## Authorization [#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 [#related] * [Participant role assignments](/docs/api-reference/reference/participant-role-assignments) * [Role-based access control](/docs/architects/components/asset-contracts/rbac) * [Authorization](/docs/compliance-security/security/authorization) * [Organization and system scope](/docs/api-reference/reference/organization-system-scope) * [Request headers](/docs/api-reference/reference/request-headers)