Organization membership API reference

A bank that runs tokenized assets keeps a tight grip on who can act inside each tenant. The organization membership endpoint adds a user to the active tenant and assigns the role they act under, so an operator can grant access programmatically instead of through the Console. Membership is the gate in front of every organization-scoped operation, so the platform checks who you are, whether the tenant is ready, and whether you may grant the requested role before it writes anything.

This write adds an existing platform user to your active organization and sets the role they act under. It does not create users, send invitations, or change a member's role after they join. For the invitation flow that brings an outside user in, see Role invitations. To read who already holds administrative authority, see Organization admins.

Endpoint

The endpoint writes to the active organization in the session. It never spans tenants: the user joins the organization you are acting in, never another one. Set the participant and wallet context with the standard request headers before you call it. See Request headers.

Required roles

Adding a member needs the identityManager system role, the same authority that governs identity management for the active system. Granting the owner role adds a second check: the caller must already hold the owner role in the organization. A caller with identityManager but not organization ownership can add members, but only with the member role. For the role model, see System account roles.

Request fields

The user must already exist on the platform. To resolve a user's userId from their national ID, wallet address, or internal ID, use User lookup.

Response fields

A successful add returns a single-resource envelope. The data object describes the new membership.

Add a member

POST /api/v2/organizations/members adds the named user to the active organization with the requested role.

curl -X POST "https://your-platform.example.com/api/v2/organizations/members" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_018f6d3e89ab7cde8123abcdefabcdef",
    "role": "member"
  }'

{
  "data": {
    "memberId": "mem_018f6d3e89ab7cde8123abcdefabcdef",
    "userId": "user_018f6d3e89ab7cde8123abcdefabcdef",
    "organizationId": "org_018f6d3e89ab7cde8123abcdefabcdef",
    "role": "member"
  },
  "links": { "self": "/v2/organizations/members" }
}

To grant organization ownership, send "role": "owner" from a caller that already holds the owner role.

curl -X POST "https://your-platform.example.com/api/v2/organizations/members" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_018f6d3e89ab7cde8123abcdefabcdef",
    "role": "owner"
  }'

How the platform checks the request

The platform runs the checks in order and stops at the first one that fails, so the error you get back names the first unmet condition.

1. An active organization is selected for the session. Without one, the request cannot resolve which organization to write to.
2. The organization has finished onboarding. Member management stays locked until the organization's deployment completes.
3. The role grant is allowed. A request to grant owner needs the caller to hold the owner role already.
4. The user is added. A rejected add, such as a user that already belongs to the organization or a user identifier that resolves to nothing, fails at this final step.

Because the checks run before the write, a failed request changes nothing. Fix the named condition and send the request again.

Errors

Each error below is terminal: the same request fails the same way until you change the request or the organization state. None of them are safe to retry unchanged. For the full catalog of platform error codes, see the Platform API error reference.

A caller that lacks the identityManager role is rejected on permission grounds before these checks run. Confirm the calling account holds identityManager for the active system when an add fails on authority rather than on one of the conditions above.

Related references

• Role invitations
• Organization admins
• User lookup
• Organization settings
• System account roles
• Platform API error reference