🔐 Authentication

{
  "usernameOrEmail": "john@example.com",
  "password": "MySecurePass123"
}

{
  "success": true,
  "message": "Logged in successfully.",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "john@example.com",
      "username": "johndoe",
      "role": "user",
      "status": "active",
      "isSubscribed": false,
      "subscriptionStatus": "incomplete"
    }
  }
}
// Cookies set: access_token (15m), refresh_token (30d)

{
  "email": "john@example.com",
  "otp": "482931"
}

{
  "success": true,
  "message": "Email verified successfully. You are now logged in.",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "john@example.com",
      "username": "johndoe",
      "role": "user"
    }
  }
}
// Cookies set: access_token, refresh_token

{
  "success": false,
  "errorCode": "OTP_INVALID",
  "message": "Incorrect code. 2 attempts remaining."
}

{
  "success": true,
  "message": "If an account with that email exists, a new code has been sent."
}

{
  "success": false,
  "errorCode": "OTP_RESEND_TOO_SOON",
  "message": "Please wait 45 seconds before requesting a new code."
}

{
  "success": true,
  "message": "Token refreshed successfully.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
// Also sets updated access_token cookie

{
  "success": false,
  "errorCode": "INVALID_REFRESH_TOKEN",
  "message": "Refresh token is invalid or expired. Please log in again."
}

{
  "success": true,
  "message": "Logged out successfully."
}

{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "username": "johndoe",
      "email": "john@example.com",
      "role": "user",
      "avatar": "https://api.dicebear.com/7.x/initials/svg?seed=johndoe",
      "language": "en",
      "timezone": "UTC",
      "preferences": { "default_results_per_page": 25 },
      "status": "active",
      "isSubscribed": true,
      "subscriptionStatus": "active",
      "haveTrial": false,
      "trialEnd": null,
      "lastActivity": "2026-04-22T10:00:00.000Z",
      "createdAt": "2026-01-15T08:00:00.000Z",
      "subscription": {
        "id": "sub_xyz",
        "status": "active",
        "periodEnd": "2026-05-22T00:00:00.000Z",
        "cancelAtPeriodEnd": false,
        "plan": {
          "id": "plan_basic",
          "name": "Basic",
          "settings": { "max_tools": 5 }
        }
      }
    }
  }
}

1. Browser navigates to → GET /api/auth/google
2. Server generates a random state UUID, stores it in KV (TTL 5 min)
3. Server redirects    → https://accounts.google.com/o/oauth2/v2/auth?...&state=...
4. User consents       → Google redirects back to:
                         GET /api/auth/google/callback?code=...&state=...
5. Server validates state against KV (CSRF check) and deletes it (single-use)
6. Server exchanges code for Google access token, fetches user profile
7. New user  → auto-registered with emailVerified: true (Google already verified it)
   Existing  → avatar updated, lastActivity stamped
8. Server sets access_token + refresh_token cookies
9. Server redirects    → {DASH_ORIGIN}/dashboard

{
  "email": "john@example.com"
}

{
  "success": true,
  "message": "If an account with that email exists, you will receive a password reset link shortly."
}

{
  "success": false,
  "errorCode": "RATE_LIMITED",
  "message": "Too many requests. Please wait and try again."
}

// The email contains a button/link pointing to:
{APP_ORIGIN}/reset-password?token=<256-bit-hex-token>

// Example:
https://app.example.com/reset-password?token=a1b2c3d4e5f6...

{
  "token": "a1b2c3d4e5f6...",
  "password": "NewSecurePass456",
  "confirmPassword": "NewSecurePass456"
}

{
  "success": true,
  "message": "Your password has been reset. You can now sign in with your new password."
}
// No auth cookies set — user must POST /login with new password

{
  "success": false,
  "errorCode": "RESET_TOKEN_INVALID",
  "message": "This password reset link is invalid or has already been used."
}

{
  "success": false,
  "errorCode": "RESET_TOKEN_EXPIRED",
  "message": "This password reset link has expired. Please request a new one."
}

{
  "success": false,
  "errorCode": "RESET_TOKEN_MAX_ATTEMPTS",
  "message": "This reset link has been invalidated after too many attempts. Please request a new one."
}

// Read token from URL query param
const params = new URLSearchParams(window.location.search);
const token = params.get("token"); // the raw 256-bit hex token

// Submit new password
const res = await fetch("/api/auth/reset-password", {
  method: "POST",
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
    "X-CSRF-Token": csrfToken,
  },
  body: JSON.stringify({
    token,
    password: "NewSecurePass456",
    confirmPassword: "NewSecurePass456",
  }),
});

// On success → redirect to /login
if (res.ok) window.location.href = "/login";

{
  "email": "john@example.com"
}

{
  "success": true,
  "message": "Verification code sent to john@example.com. It expires in 10 minutes."
}

{
  "success": false,
  "errorCode": "USER_ALREADY_EXISTS",
  "message": "An account with this email already exists."
}

{
  "success": false,
  "errorCode": "OTP_RESEND_TOO_SOON",
  "message": "Please wait 45 seconds before requesting a new code."
}

{
  "email": "john@example.com",
  "otp": "483910"
}

{
  "success": true,
  "data": {
    "registrationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
// Store this token and pass it to Step 3. Expires in 15 minutes.

{
  "success": false,
  "errorCode": "OTP_INVALID",
  "message": "Incorrect code. 2 attempts remaining."
}

{
  "success": false,
  "errorCode": "OTP_EXPIRED",
  "message": "This code has expired. Please request a new one."
}

{
  "registrationToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "johndoe",
  "password": "MySecurePass123",
  "confirmPassword": "MySecurePass123",
  "name": "John Doe"
}

{
  "success": true,
  "message": "Account created successfully. You are now logged in.",
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "john@example.com",
      "username": "johndoe",
      "role": "user"
    }
  }
}
// Cookies set: access_token (15m), refresh_token (30d)

{
  "success": false,
  "errorCode": "REGISTRATION_TOKEN_INVALID",
  "message": "Registration token is invalid or has expired. Please start again."
}

{
  "success": false,
  "errorCode": "USER_ALREADY_EXISTS",
  "message": "Username is already taken."
}

{
  "success": true,
  "message": "Verification code sent to john@example.com. It expires in 10 minutes."
}

{
  "success": false,
  "errorCode": "OTP_RESEND_TOO_SOON",
  "message": "Please wait 42 seconds before requesting a new code."
}