Organization admins API reference

An auditor reviewing a regulated deployment asks one question first: who holds administrative authority here, and can you see that list on demand? The organization admins endpoint answers it. You get the admin users of the active organization as a single, paged, filterable list, so a governance review or an access certification reads from the platform rather than from a chain explorer.

The list is read-only. It reports admin users that already hold their roles, and it never grants roles, revokes roles, or creates users. For authentication and base URL setup, see Getting started. The active organization and system context bound every read, as described in Organization and system scope.

Endpoint

The endpoint uses the collection envelope with data, meta, and pagination links. Each row is one admin user. A caller needs the system admin-list permission for the active organization; without it the request is rejected rather than returned empty.

How the admin set is built

An admin user is a platform user who holds a system administrative role on chain. The platform builds the set by reading the current system role holders from the access-control register, then matching each holder's wallet address to the profile that owns it. A wallet that holds a role but maps to no user profile does not appear, and a user appears once even when several of their wallets carry roles.

Two consequences follow for a reviewer:

• The list reflects live on-chain authority. A role granted or revoked on chain changes the membership of this list, not a separate platform-only flag.
• The list is bounded to the active organization. Switching context returns that tenant's admin set, never a deployment-wide roster.

List organization admins

GET /api/v2/user-admins returns the admin users for the active organization. The default sort is by name in ascending order.

curl --globoff "https://your-platform.example.com/api/v2/user-admins?filter[q]=ada" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "usr_01HXYZ",
      "name": "Ada Lovelace",
      "email": "[email protected]",
      "wallet": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "signingAddress": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "executorAddress": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "isAdmin": true,
      "lastLoginAt": "2026-06-20T09:14:00.000Z",
      "createdAt": "2026-01-08T11:02:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "facets": {}
  },
  "links": {
    "self": "/v2/user-admins?page[offset]=0&page[limit]=50",
    "first": "/v2/user-admins?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/user-admins?page[offset]=0&page[limit]=50"
  }
}

Admin fields

The row shares the same user shape returned by the user lookup endpoints, so a reviewer can move from the admin roster to a single user without remapping fields.

Query controls

The response reports a single meta.total for the current filters, which counts the admins that match before paging. Read meta.total alongside the page of rows in data to drive pagination controls.

Who can list admins

The endpoint is gated on the system admin-list permission for the active organization, which an admin or system-manager role grants. A caller that holds the permission reads the full admin set. A caller that does not is rejected, because the admin roster is a governance surface rather than a public directory.

The gate runs before the list is built, so a request can be rejected for setup reasons rather than returning a list:

• The organization has no deployed system yet. The request is rejected with a "system not deployed" error. Deploy a system before listing its admins.
• The system has no access-control context available. The request is rejected with a "system access control unavailable" error.
• The caller lacks the admin-list permission. The request is rejected as unauthorized.

A valid empty result is different from these rejections. When the gate passes but no role holder resolves to a platform user profile, the endpoint returns a successful empty list: data is empty and meta.total is 0. Treat a rejection as a setup or permission signal, and treat an unexpected empty list as a gap between on-chain role holders and platform user profiles, not proof that the organization runs without admins.

How it differs from the other people surfaces

This endpoint is one of several read-only surfaces over the people and roles in an organization. Choose by the question you are answering.

When to use it

Use this endpoint when you need to:

• Produce an access certification or governance review that lists every admin user of an organization.
• Reconcile administrative authority against an expected roster during an audit.
• Drive an admin-management view that filters by name, email, or wallet and sorts by recent activity.
• Confirm that a role change on chain is reflected in the organization's admin set.

For the model behind the roles themselves, see Role-based access control.