Create users

The create-user API creates a DALP user account in the caller's active organisation. It also provisions the wallet and identity that let the user hold assets. Use it for controlled setup, demos, test accounts, and passive holders who need an account before they sign in.

Use invitations instead when the person should accept an invitation and control their first login from the start. For the workspace flow, see Create users from the web interface.

Prerequisites

• An API key for a caller with permission to create users in the active organisation.
• Wallet verification for the caller when the identity creation transaction is authorised.
• A unique email address for the user being created.
• An active organisation in the caller's session. DALP rejects creation when the request has no active organisation.

Create a user

curl -X POST "https://your-platform.example.com/api/user/create" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Northwind Treasury Holder",
    "email": "[email protected]",
    "walletVerification": {
      "secretVerificationCode": "123456"
    }
  }'

{
  "id": "usr_123abc",
  "name": "Northwind Treasury Holder",
  "email": "[email protected]",
  "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "identity": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
}

Request fields

What DALP creates

DALP creates four linked records for the user:

Endpoint variants

DALP exposes the create-user operation through two public API paths.

Use the path that matches the rest of your integration. Both paths create the same account, wallet, organisation membership, and identity.

Operating notes

• Creating a user is not the same as inviting a person. The create-user route does not send an invitation email.
• The platform does not return the generated password to administrators. If the created user needs to sign in, they must use the password-reset flow for the created email address.
• Creating the account does not register the identity in the identity registry. Register the identity before using the account in workflows that require registry membership.
• The caller needs create-user permission. The route checks the caller's system permissions before it creates the account.
• Reusing an existing email address returns a conflict instead of creating another account, unless the request qualifies for the resume path described below.

Resume a stranded account

Create-user runs in two stages. DALP first commits the account and wallet, then deploys the on-chain identity. If the second stage fails, after a queue, network, transaction, or gateway-timeout error, the account and wallet persist but the identity does not. Reading the user back shows a wallet with no identity address.

When the second stage fails this way, the request returns the USER_IDENTITY_REGISTRATION_INCOMPLETE error (DALP-0671), which the platform marks retryable. Treat it as a signal that the account and wallet were created and that the create is safe to retry, not as a total failure. A gateway timeout such as a 504 carries the same meaning: the platform can keep working after the client connection drops, so confirm the outcome by reading the user back or by retrying rather than assuming nothing was created.

Re-submit the same create-user request to finish a stranded account. When the email already belongs to a user in the caller's organisation that has a wallet but no on-chain identity contract, DALP skips account creation and resumes identity creation for the existing wallet. You do not delete and recreate the account.

Retry once rather than in a tight loop. If the resume attempt still fails, the response carries the underlying error instead of the retryable signal, so you can diagnose a persistent cause rather than retrying against it.

The resume match is keyed on the organisation and the email address, not on a per-request idempotency key. A retry with a fresh idempotency key still resumes the same account, as long as the organisation and email match.

DALP returns a conflict, not a resume, when the existing email is not a partial failure: a user that already has an on-chain identity in any state, a user outside the caller's organisation, or an account DALP cannot resolve to a wallet. In those cases the request reports that the email already exists, the same as before.

Recover an unregistered identity

If the wallet DALP creates or resolves for the user already has an on-chain identity, the request returns a conflict instead of deploying a second identity. The user account and wallet are still created, but the response omits the wallet address. To recover: retrieve the user by email to get the wallet, read the identity by wallet to confirm its state, and then register it with POST /system/pending-identity-registrations if it is not registered yet. The Register user guide covers the read-identity-by-wallet and queued registration steps end to end.

Related guides

• Create users from the web interface for the same onboarding choice in the DALP workspace.
• Register user for adding a wallet-backed identity to the registry.
• Getting started with the API for API-key setup.