Invitations with roles API

Overview

This endpoint creates an organization invitation and records the on-chain roles the invitee should hold. When the invitee accepts and finishes onboarding, the platform grants those roles on-chain automatically. You set the roles once, at invite time, instead of inviting the person and then granting each role separately after they join.

It is the only way to set an invitation's on-chain roles. The standard invitation flow can invite a member but cannot pre-assign on-chain roles, so use this endpoint whenever a new user needs system authority from the moment they join. An invite with no on-chain roles belongs on the standard invitation flow, not here.

Access and scope

The call runs inside your active organization and the invitation belongs to that organization. The platform reads the active organization and chain context from the request the same way every other write does. See Request headers for how that context is set.

Setting on-chain roles is privileged, so the platform gates it on the inviter's wallet verification. A human session must prove control of its wallet with a PIN, a one-time passcode, or multi-factor verification before the invitation is created. An API-key session used for automation, such as the CLI, is exempt from the interactive gate and may omit the verification field.

Requirements

Before you call this endpoint:

• Authenticate as a member who can invite users in the active organization.
• Choose the platform membership role for the invitee: owner or member. The default is member.
• Choose at least one on-chain role to grant on acceptance.
• For a human session, include wallet verification. For an API-key session, you can omit it.

Invite a user with roles

Send the invitee's email, the platform role, the on-chain roles to grant, and your wallet verification.

curl "https://your-platform.example.com/api/v2/role-invitations" \
  -X POST \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member",
    "onChainRoles": ["complianceManager", "tokenManager"],
    "walletVerification": {
      "secretVerificationCode": "123456",
      "verificationType": "PINCODE"
    }
  }'

{
  "id": "inv_123abc",
  "email": "[email protected]",
  "role": "member",
  "status": "pending",
  "onChainRoles": ["complianceManager", "tokenManager"],
  "expiresAt": "2026-07-03T09:10:29.428Z"
}

The response confirms the invitation that was created. status is pending until the invitee accepts. onChainRoles echoes the roles recorded for the grant, and expiresAt is when the invitation lapses if it is not accepted.

The roles are not granted yet at this point. They are recorded against the invitation and granted on-chain only after the invitee accepts and completes onboarding. If the invitee never accepts, no role is granted.

Request fields

The walletVerification object carries the verification code and its type:

On-chain roles

onChainRoles accepts system-level access-control roles. Each role carries a specific authority across the deployment:

For the model behind these roles, see Role-based access control and Authorization. To read which roles a participant already holds, see Participant role assignments.

Response fields

Acceptance error codes

This endpoint records the invitation. The invitee accepts it later through the acceptance flow, which checks the invitation state before granting any role. When acceptance cannot proceed, the platform returns a stable DALP-NNNN identifier. Show the invitee the matching next step instead of retrying a request that keeps failing. For the full catalog with HTTP status and retryability per code, see the Platform API error reference.

DALP-0030 is a success-adjacent state: the invitation is already accepted, so the invitee can proceed rather than retry. DALP-0051, DALP-0052, and DALP-0053 are terminal for that invitation, so ask the organization to send a fresh one. DALP-0029 is not terminal: the invitation is still valid, and signing in with the invited email address lets the invitee accept it without a new invitation being issued.

Related

• Invitation onboarding API
• Organizations administration API
• Participant role assignments
• Role-based access control
• Authorization
• Request headers