Create user account

Overview

Before you can issue a credential to someone, they need an account in your organisation. Onboarding creates two things at once: an identity record and the custodial wallet attached to it. After this step the user can sign in, accept credential offers, and respond to presentation requests. You do this once per user, the first time you onboard them.

Endpoint

POST https://test.didxtech.com/consumer-onboarding/api/users

Request

curl -X POST "https://test.didxtech.com/consumer-onboarding/api/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "johndoe",
    "firstName": "John",
    "lastName": "Doe",
    "externalIdentifier": "PARTNER-ID-12345"
  }'

Request body

You must supply at least one of email or username. The rest are optional.

`email` (optional)

The user’s email address. If supplied, it’s used for password-recovery flows and as the default sign-in identifier.

`username` (optional)

A handle for the user. May contain only alphanumeric characters, dots, underscores, or hyphens. Useful when the user doesn’t have (or doesn’t want to share) an email, or when you want stable, human-readable identifiers in your own system. If you omit username, the platform derives one from the email.

`firstName`, `lastName` (optional)

The user’s name as you’d like it shown in their wallet and in consent dialogs. Update later if you need to.

`externalIdentifier` (optional)

Your own id for the user (CRM id, partner reference number, or anything stable on your side). Stored against the account so you can look the user up by it later (see Lookup and IdP linking). Doesn’t have to be unique across organisations, but should be unique within yours.

Response

HTTP 201 Created

{
  "email": "user@example.com",
  "username": "johndoe",
  "tempPassword": "!w&3WgYeEGMv"
}

Field	Notes
`email`	Echoed back if you supplied one.
`username`	The username on the account, either what you supplied or one derived from the email.
`tempPassword`	A one-time password the user will need on first sign-in. Always present. Communicate it to the user out-of-band (e.g. email it yourself) and require them to change it on first login.

Error responses

Status	When you’ll see it
`400`	Validation failed: neither `email` nor `username` was supplied, the email format is invalid, or the username doesn’t match the allowed pattern.
`401`	Missing or invalid bearer token.
`409`	Conflict: the username is taken by another organisation, or the supplied email and username belong to different existing users.

What happens next

The user receives the tempPassword. You’re responsible for getting it to them, typically via email.
On first sign-in they’re required to change it.
Any credentials you issue to them appear as pending offers in their wallet, awaiting their acceptance.

Lookup and IdP linking

Related endpoints on the same consumer-onboarding API:

GET /users. List users in your organisation.
GET /users/by-external-identifier/{externalIdentifier}. Find a user by the externalIdentifier you supplied at onboarding.
GET /users/{username}/external-identifier. Read the external identifier stored against an existing user.
PATCH /users/{username}/idp-link. Link the account to an external identity provider.

Full schemas live in the Consumer Onboarding API reference.

Overview

User Onboarding

Issuance

Verification

Webhooks

Custom Templates (advanced)

Errors

Overview

Endpoint

Request

Request body

`email` (optional)

`username` (optional)

`firstName`, `lastName` (optional)

`externalIdentifier` (optional)

Response

Error responses

What happens next

Lookup and IdP linking

​Overview

​Endpoint

​Request

​Request body

​email (optional)

​username (optional)

​firstName, lastName (optional)

​externalIdentifier (optional)

​Response

​Error responses

​What happens next

​Lookup and IdP linking

Overview

Endpoint

Request

Request body

`email` (optional)

`username` (optional)

`firstName`, `lastName` (optional)

`externalIdentifier` (optional)

Response

Error responses

What happens next

Lookup and IdP linking