Authentication Module
Identity management and session control via Email OTP and secure cookies.
Description
The Authentication module provides the gateway to the VeriWorkly ecosystem. It utilizes a passwordless Email OTP (One-Time Password) flow to ensure a friction-less and secure user experience.
Once authenticated, the system establishes a secure, HTTP-only session that persists across the dashboard and resume builder.
Authentication Flow
VeriWorkly follows a simple 2-step verification process:
- OTP Request:
POST /auth/email-otp/send-verification-otpwith{ email, type: "sign-in" }. A short-lived numeric code is sent via our SMTP provider. The response is always{ "success": true }— it does not reveal whether the address has an account. - Sign in:
POST /auth/sign-in/email-otpwith{ email, otp }. On success a secure cookie is set and the session token plus user record are returned. A new account is created automatically on first sign-in.
These routes do not use the standard response envelope
Authentication is delegated to Better Auth, mounted at /api/v1/auth. Its endpoints return
Better Auth's own payload shapes — they are not wrapped in the { success, message, data }
envelope used everywhere else in this API.
Security & session management
| Feature | Implementation |
|---|---|
| Protocol | Passwordless Email OTP. Codes expire after 5 minutes and allow 3 attempts. |
| Session Type | HTTP-only, Secure, SameSite cookies to prevent CSRF and XSS. |
| Provider | Powered by Better Auth with a Prisma adapter for persistent session storage. |
| Rate limits | 3 requests/minute per IP for sending a code; 20/minute for signing in. Exceeding either gives 429. |
Available Endpoints
POST /auth/email-otp/send-verification-otp— Send OTPPOST /auth/sign-in/email-otp— Sign In With Email OTPGET /auth/get-session— Get SessionPOST /auth/sign-out— Sign Out
Readiness CheckGET
Deep readiness probe for deploy gates and manual diagnostics. Runs a `SELECT 1` against PostgreSQL and a `PING` against Redis, and returns `503` if either is unreachable. Because it wakes database compute on every call, prefer `GET /api/v1/health` for routine uptime monitoring. Like the liveness probe, it requires no authentication.
Send OTPPOST
Emails a one-time password to the given address. Authentication is handled by **Better Auth**, mounted at `/api/v1/auth`. Its endpoints return Better Auth's own payloads — they are **not** wrapped in the `{ success, message, data }` envelope the rest of this API uses. Rate limited to 3 requests per minute per IP.