v9 (current) v8
Edit Page

User Registration & Email Verification

RESTHeart

Registration flow

POST /auth/register is the public signup endpoint. It creates a new user and a new tenant in a single atomic operation.

Request

POST /auth/register
Content-Type: application/json

{
  "firstName": "Alice",
  "lastName":  "Rossi",
  "teamName":  "Acme",
  "email":     "alice@acme.com",
  "password":  "correct-horse-battery"
}

Server-side steps

  1. Validate all required fields.

  2. Enforce password strength via zxcvbn (score ≥ minimumPasswordStrength, default 3).

  3. Check email uniqueness — 409 Conflict if already registered.

  4. Generate a cryptographically random verificationToken (256-bit) and verificationCreatedAt timestamp.

  5. Create the tenant document (status: active).

  6. Create the user document (status: pending_verification) with the verification token.

  7. Create a membership document linking the user to the tenant as owner.

  8. Send a verification email containing a one-time link:

    {baseAppUrl}/auth/verify?email=alice@acme.com&token=<verificationToken>

  9. Return 201 Created.

Response

{ "message": "Registration successful. Check your email to verify your address." }

Error responses

Status Reason

400

Missing or invalid fields; password too weak

409

Email already registered

Email verification

GET /auth/verify?email=…​&token=…​ is sent as a link in the registration email.

Server-side steps

  1. Extract email and token from the query string.

  2. Find the user by email.

  3. Compare token against verificationToken using constant-time comparison (timing-attack mitigation).

  4. Check that verificationCreatedAt is within the TTL (verificationTokenTtlDays, default 7 days).

  5. Set status: active and $unset verificationToken verificationCreatedAt.

  6. Issue a JWT access token + refresh cookie.

  7. Redirect to {baseAppUrl}/app.

Expired token

If the token has expired, the endpoint returns 400 with a message inviting the user to request a new verification email from the login page.

Note
 Re-sending a verification email is triggered by POST /auth/resend-verify (not yet implemented in v1 — users can contact support or attempt login which will prompt re-verification).