Overview
The first step in the issuance workflow is creating a youth account. This provisions a Keycloak identity in the Consumers realm and initialises a wallet tenant — giving the youth a place to receive and store credentials.
This is more than “creating a user.” The API provisions a full wallet tenant backed by the Credo SSI framework.
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 | Yes | Youth’s email address |
firstName | string | Yes | Youth’s first name |
lastName | string | Yes | Youth’s last name |
Response
The response differs depending on whether the youth is new or already exists in the system.
New User — HTTP 201 Created
{
"email": "[email protected]",
"tempPassword": "!w&3WgYeEGMv"
}
| Field | Description |
|---|
email | The youth’s email address |
tempPassword | A temporary password generated for the youth |
Existing User — HTTP 201 Created
If the youth already has an account (created by another partner), the API still returns 201 but with an empty tempPassword. In the YOMA ecosystem, youth frequently interact with multiple partners — Thandi might be onboarded by multiple organisations. The account only needs to be created once.
{
"email": "[email protected]",
"tempPassword": ""
}
tempPassword tells you the account already exists. This is not an error — proceed directly to credential issuance. The youth’s wallet is already provisioned.
This endpoint is idempotent for the same email — it won’t create a duplicate account. But because it returns 201 in both cases (not 409 or 200), the only way to detect an existing account is to check whether tempPassword is empty. Build your onboarding flow to handle this: if tempPassword is empty, skip sending onboarding emails.
What Happens on the Youth’s Side
New account:
- A Keycloak account is created in the Consumers realm
- A wallet tenant is initialised — this is where credentials will be stored
- A temporary password is generated and communicated to the youth via email
- The youth must update this password on first login
- Once they sign in, any previously issued credentials appear as pending items waiting for acceptance
Existing account:
The youth already has a wallet. Any credentials you issue will be delivered to their existing wallet.
Async pipeline: You don’t need to wait for the youth to activate their account before issuing credentials. Credentials issued before activation are held in custody and delivered automatically when the youth signs in.
