Skip to main content
New accounts require three steps: request an email verification code, verify the email, then complete registration with your personal details.

​
Registration flow

1

Send a verification email

Call POST /auth/verification-mail with the email address you want to register. The platform sends a one-time verification code to that address.
2

Verify your email

Call GET /auth/verify with the email and the code from the email. The platform marks the address as verified.
3

Complete registration

Call POST /auth/signup with your name, password, and the same email address. The account is created and ready to use.
4

Sign in

Use POST /auth/signin to obtain a JWT access token. See Login and session management for details.

​
Send verification email

POST /auth/verification-mail Sends a verification code to the provided email address. This is the first step in the registration flow.

​
Query parameters

​
clientAlias
string
Optional alias that scopes the verification email to a specific front-end client (for example, "VERIFIER"). Use GET /auth/clientAliases to retrieve valid values for your deployment. When omitted, the default client is used.

​
Request body

​
email
string
required
The email address to verify. Must be a valid email, maximum 256 characters. Leading and trailing whitespace is stripped; the value is lowercased automatically.
​
brandLogoUrl
string
Optional URL of a brand logo to embed in the verification email. Must include a protocol and a valid TLD (for example, https://example.com/logo.png).
​
platformName
string
Optional display name of your platform, shown in the verification email body (for example, "MyPlatform").

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/verification-mail \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com"
  }'
201 response
{
  "statusCode": 201,
  "message": "Verification code sent successfully"
}

​
Verify email

GET /auth/verify Validates the verification code sent to the user’s email address. Must be called before completing registration.

​
Query parameters

​
email
string
required
The email address to verify. Maximum 256 characters. Lowercased and trimmed automatically.
​
verificationCode
string
required
The verification code received in the email.

​
Examples

curl --request GET \
  --url "http://localhost:5000/v1/auth/verify?email=alice%40example.com&verificationCode=123456"
200 response
{
  "statusCode": 200,
  "message": "Email verified successfully"
}

​
Error responses

StatusDescription
400 Bad RequestThe verification code is invalid or has expired.

​
Complete registration

POST /auth/signup Creates the user account. Requires that the email address has already been verified via GET /auth/verify.

​
Request body

​
email
string
required
The verified email address. Must be a valid email.
​
firstName
string
required
The user’s first name. Minimum 2 characters, maximum 50 characters.
​
lastName
string
required
The user’s last name. Minimum 2 characters, maximum 50 characters.
​
password
string
required
The password to set for the new account.
​
isPasskey
boolean
Set to true to register the account for passkey (FIDO2) authentication instead of a password. Defaults to false.
​
isHolder
boolean
Set to true to register the account as a credential holder. Defaults to false.

​
Response

​
statusCode
number
HTTP status code. 201 on success.
​
message
string
Human-readable result message.
​
data
object
The newly created user object.

​
Examples

curl --request POST \
  --url http://localhost:5000/v1/auth/signup \
  --header "Content-Type: application/json" \
  --data '{
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Smith",
    "password": "S3cureP@ss!"
  }'
201 response
{
  "statusCode": 201,
  "message": "User registered successfully",
  "data": {
    "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": "Smith"
  }
}

​
Error responses

StatusDescription
400 Bad RequestOne or more required fields are missing, invalid, or the email has not been verified.
409 ConflictAn account with this email address already exists.

​
Complete registration flow example

The following sequence shows all three steps together. 
curl --request POST \
  --url http://localhost:5000/v1/auth/verification-mail \
  --header "Content-Type: application/json" \
  --data '{"email": "alice@example.com"}'
The verification code from step 2 is single-use and time-limited. If it expires, repeat step 1 to receive a new code.

Build docs developers (and LLMs) love

Get started for freeTalk to us