Registration

Register a new user account on the CREDEBL Platform.

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

curl --request POST \
  --url http://localhost:5000/v1/auth/verification-mail \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]"
  }'

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

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

Status	Description
400 Bad Request	The 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 (standard account)

curl --request POST \
  --url http://localhost:5000/v1/auth/signup \
  --header "Content-Type: application/json" \
  --data '{
    "email": "[e-mail]",
    "firstName": "Alice",
    "lastName": "Smith",
    "password": "S3cureP@ss!"
  }'

201 response

{
  "statusCode": 201,
  "message": "User registered successfully",
  "data": {
    "id": "d8b9b81b-7232-4a7f-b9d3-4f7226129677",
    "email": "[e-mail]",
    "firstName": "Alice",
    "lastName": "Smith"
  }
}

Error responses

Status	Description
400 Bad Request	One or more required fields are missing, invalid, or the email has not been verified.
409 Conflict	An account with this email address already exists.

---

Complete registration flow example

The following sequence shows all three steps together.

step 1 — send verification email

curl --request POST \
  --url http://localhost:5000/v1/auth/verification-mail \
  --header "Content-Type: application/json" \
  --data '{"email": "[e-mail]"}'

The verification code from step 2 is single-use and time-limited. If it expires, repeat step 1 to receive a new code.