Authentication

TurboKit includes a complete authentication system with JWT tokens, sessions, email verification, and password reset.

Authentication Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Database

    User->>Frontend: Enter credentials
    Frontend->>API: POST /auth/login
    API->>Database: Verify user
    Database-->>API: User found
    API->>API: Generate JWT + Refresh Token
    API-->>Frontend: Tokens + User info
    Frontend->>Frontend: Store tokens, set session
    Frontend-->>User: Redirect to dashboard

API Endpoints

Endpoint	Method	Description
`/auth/register`	POST	Create new account
`/auth/login`	POST	Authenticate user
`/auth/logout`	POST	End session
`/auth/refresh`	POST	Refresh access token
`/auth/verify-email`	GET	Verify email address
`/auth/forgot-password`	POST	Request password reset
`/auth/reset-password`	POST	Reset password
`/auth/me`	GET	Get current user

Registration

// POST /auth/register
const response = await fetch("/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    name: "John Doe",
    password: "securepassword123",
  }),
});

Response:

{
  "success": true,
  "message": "Registration successful. Please check your email to verify your account.",
  "data": {
    "user": {
      "id": "clx123...",
      "email": "user@example.com",
      "name": "John Doe",
      "emailVerified": null
    }
  }
}

// POST /auth/login
const response = await fetch("/auth/login", {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "user@example.com",
    password: "securepassword123",
  }),
});

Token Management

Access Token (JWT)

Lifetime: 15 minutes
Storage: Memory (not persisted)
Usage: API requests (Authorization header)
Contains: userId, email, expiry

Refresh Token

Lifetime: 7 days
Storage: httpOnly cookie
Usage: Get new access tokens
Security: httpOnly, secure, sameSite=lax

Session Token

Lifetime: 7 days
Storage: httpOnly cookie
Usage: Backend session validation
Security: httpOnly, secure, sameSite=lax

Security Features

Password Hashing

Uses Argon2 (industry standard):

import { hash, verify } from "@node-rs/argon2";

const hashedPassword = await hash(password, {
  memoryCost: 65536, // 64MB
  timeCost: 3,
  parallelism: 4,
});

const isValid = await verify(hashedPassword, password);

Rate Limiting

Authentication routes are rate-limited:

const authRateLimiter = rateLimit({
  duration: 60 * 1000, // 1 minute
  max: 5, // 5 requests
  scoping: "scoped",
});

Environment Variables

# JWT
JWT_SECRET=your-super-secret-key-change-in-production

# Session
SESSION_SECRET=another-super-secret-key

# Email (Resend)
RESEND_API_KEY=re_your_api_key
FROM_EMAIL=noreply@yourdomain.com

# App
APP_NAME=TurboKit
FRONTEND_URL=http://localhost:4100
NODE_ENV=development

Best Practices

Password Requirements: Enforce minimum 6 characters
Rate Limiting: Protect auth endpoints from brute force attacks
Email Verification: Require email verification before accessing sensitive features
Token Rotation: Refresh tokens regularly to minimize exposure
Secure Cookies: Use httpOnly, secure, and sameSite attributes
HTTPS Only: Always use HTTPS in production

Warning: Always use HTTPS in production to protect credentials and tokens during transmission.

Authentication

On this page