Skip to main content

​
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

​
Request

​
Request body

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

​
email (optional)

The user’s email address. If you supply one, the platform uses it for password-recovery flows and as the default sign-in identifier.

​
username (optional)

A handle for the user. It may contain only alphanumeric characters, dots, underscores, or hyphens. This is useful when the user has no email or doesn’t want to share one, 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, such as a CRM id, a partner reference number, or anything stable on your side. The platform stores it against the account so you can look the user up by it later (see Lookup and IdP linking). It doesn’t have to be unique across organisations, but should be unique within yours.

​
sendOnboardingEmail (optional)

Whether to send the Keycloak onboarding email that walks the user through setting a password, verifying their email, and configuring strong auth. Defaults to true when you supply an email and the environment has onboarding contexts configured. Requires email.

​
onboardingContext (optional)

Which onboarding context to use from the server-side registry. Defaults to me-wallet.

​
strongAuth (optional)

Which strong-auth setup to include in the email stream. Defaults to the context’s own defaultStrongAuth.

​
Response

HTTP 201 Created
Only tempPassword is guaranteed present. The resend endpoint takes the username as a path parameter, so if you need it for later calls, either supply it yourself at onboarding or look it up with GET $BASE_URL/consumer-onboarding/api/users.
Check emailSent, not the HTTP status. A 201 with emailSent: false means the account exists but the user never got their link. They cannot sign in until you resend it. Treat it as a failure in your integration.
tempPassword is a leftover from the older flow. On the email pathway it comes back as an empty string, so don’t branch on its presence. Branch on emailSent.

​
Error responses

​
What happens next

The platform sends the onboarding email for a new user with an email, as long as sendOnboardingEmail is not false:
  • The user receives an onboarding email from Keycloak with a single-use, time-boxed link.
  • Following it, they set their own password, verify their email, and configure strong auth.
  • Any credentials you issue in the meantime wait as pending offers in their wallet.
If you pass sendOnboardingEmail: false, or onboard by username with no email, the platform sends no email and getting the user signed in is up to you.
Listing users later with GET $BASE_URL/consumer-onboarding/api/users returns a different shape, including a status of pending or active. pending means the user still has no way to sign in, with no credentials, no federated identity, and no QiD enrolment.

​
Resend the invite

If the email bounced, expired, or was lost:
You can only resend to a pending invitee. A user who already has stored credentials, a federated identity, or QiD enrolment is active and returns 409.

​
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.
  • POST /users/{username}/onboarding-email. Resend the onboarding email to a pending invitee.
Full schemas live in the Consumer Onboarding API reference.