Participant assumption API reference

A user signs in as one participant, their own person participant, but may be entitled to act for others. An operations lead who administers an organization can act as that organization to issue, transfer, or service its assets. Participant assumption is the model that decides which participants a user may step into. One endpoint lists the participants a user may assume, so an interface can offer an acting-as switcher. The X-Participant request header carries the choice on each call.

Assumption decides only the identity context a request runs in. It never widens what that identity may do. The platform checks assumption before it queues any blockchain operation, and once a request acts as a participant, the platform still enforces that participant's on-chain roles for every operation. A user who may act as an organization but lacks the role for an operation still has the operation rejected.

Who a user may assume

The platform derives the assumable set from identity and role state that already exists. No separate delegation grant exists to manage.

The organization check is scoped to the network the request targets. A user is entitled to act as an organization on a given network only when their executor holds a qualifying role in that organization's system on that network. The check reads the same role state the platform uses to authorize on-chain operations, so the acting-as list and the enforcement layer stay consistent.

List assumable participants

GET /api/v2/participants/assumable returns the participants the authenticated user may assume on the active network. Use it to populate an acting-as switcher.

curl --globoff "https://your-platform.example.com/api/v2/participants/assumable" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": [
    {
      "id": "pp_018f6d3e-89ab-7cde-8123-abcdefabcdef",
      "kind": "person",
      "displayName": "Ada Lovelace",
      "gatingRole": null
    },
    {
      "id": "op_018f6d40-1234-7cde-9abc-abcdefabcdef",
      "kind": "organisation",
      "displayName": "Northwind Issuer",
      "gatingRole": "organisationIdentityManager"
    }
  ],
  "meta": {
    "total": 2
  },
  "links": {
    "self": "/v2/participants/assumable?page[offset]=0&page[limit]=50",
    "first": "/v2/participants/assumable?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/participants/assumable?page[offset]=0&page[limit]=50"
  }
}

The list always includes the user's own person participant. It includes one entry for each organization the user may act as on the active network. The response uses the collection envelope with data, meta, and pagination links.

Assumable participant fields

Query controls

The assumable set is scoped to the authenticated user across the organizations the user belongs to. It reports the participant identifier, kind, name, and qualifying role. It does not expose another user's assumable set, and it does not return asset or financial data.

Act as an assumed participant

To act as a participant from the list, send its id in the X-Participant header on the request. When the header is absent, the request acts as the authenticated session participant.

curl -X POST "https://your-platform.example.com/api/v2/tokens/0x1234567890AbcdEF1234567890aBcdef12345678/mints" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: mint-2026-06-29-001" \
  -H "X-Participant: op_018f6d40-1234-7cde-9abc-abcdefabcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["0x1111111111111111111111111111111111111111"],
    "amounts": ["1000"]
  }'

This request acts as the organization participant op_018f6d40-1234-7cde-9abc-abcdefabcdef and submits the mint. The platform confirms the user may assume that participant, then enforces the participant's on-chain roles for the mint itself. For the executor and network headers that pair with X-Participant, see Request headers.

When a user may not assume a participant

The platform applies the assumption check before it queues any blockchain operation.

Every denial returns the same X_PARTICIPANT_FORBIDDEN error whether the named participant is one the user cannot assume, belongs to another organization, or is absent. The uniform response means a caller cannot probe the header to discover which participants exist. For the full entry, see DALP-0524.

When to use it

Use participant assumption when you need to:

• Show an acting-as switcher that lists every participant the signed-in user may act as.
• Resolve the correct X-Participant value before submitting a request on behalf of an organization.
• Confirm a user may act as an organization on the active network before offering organization operations in an interface.

To read an organization's participant directory for recipient selection rather than the user's own assumable set, see Participant directory. To read a participant's role assignments, see Participant role assignments.