Overview
The first step in the issuance workflow is creating a youth account. This provisions an identity in the Consumers realm and initialises a wallet tenant — giving the youth a place to receive and store credentials.
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": "[email protected]",
"firstName": "Thandi",
"lastName": "Molefe"
}'
Request Body
| Field | Type | Required | Description |
|---|
email | string | No* | Youth’s email address |
username | string | No* | Username (alphanumeric, ., -, _) |
firstName | string | No | Youth’s first name |
lastName | string | No | Youth’s last name |
externalIdentifier | string | No | Your system’s identifier for this youth |
*At least one of email or username must be provided. Behaviour varies depending on the combination — see the API Reference for full details.
Response
The response differs depending on whether the youth is new or already exists.
New User — HTTP 201 Created
{
"data": {
"email": "[email protected]",
"username": "thandi.molefe",
"tempPassword": "!w&3WgYeEGMv"
}
}
| Field | Description |
|---|
email | The youth’s email address |
username | The assigned username |
tempPassword | A temporary password for the youth |
Existing User — HTTP 201 Created
If the youth already has an account, the API still returns 201 but with an empty tempPassword. This is not an error — proceed directly to credential issuance.
{
"data": {
"email": "[email protected]",
"username": "thandi.molefe",
"tempPassword": ""
}
}
The only way to detect an existing account is to check whether tempPassword is empty. If empty, skip sending onboarding emails.
Idempotency
This endpoint is idempotent for the same email — it won’t create duplicate accounts. It returns 201 in both new and existing cases.
A 409 Conflict is returned if the username is already taken by a different email, or there’s a mismatch between the provided email and username.
