Hybrid Authentication Blueprint

Hybrid authentication combines stateless JWT access tokens with server-tracked sessions to give you fast authorization with strong session control.

This blueprint ships with credential-based login, OAuth providers, refresh-token rotation, and session management backed by Redis.

Installation Guide

Add the hybrid authentication blueprint using the Servercn CLI:

npx servercn-cli add blueprint hybrid-auth

Features

Hybrid Token Model - JWT access tokens with Redis-backed sessions
Refresh Token Rotation - Secure session renewal and reuse detection
Credential Login - Email + password signup/signin with OTP verification
OAuth Providers - Google, GitHub, and Facebook authentication flows
Session Management - View and revoke sessions per device
Profile Management - Update profile info and avatar uploads
Account Safety - Rate limits, soft delete, and reactivation

Architecture Options

This blueprint is available in two architectures:

MVC Architecture

Traditional Model-View-Controller pattern with separated concerns:

Controllers handle request logic
Models define MongoDB schemas
Services encapsulate business logic
Routes define API endpoints
Middlewares handle cross-cutting concerns

Feature Architecture

Domain-driven modular structure organized by feature:

Each module contains controller, service, routes, models
Shared utilities in common directories
Scales well for large applications

Authentication Flow

Signup sends an OTP to the user’s email and stores pending data in Redis.
Verify User confirms the OTP, creates the user record, and marks email as verified.
Signin issues access + refresh tokens and creates a Redis session.
Refresh Token rotates tokens and reissues session cookies.
Sessions list active devices and revoke them on demand.

API Endpoints

All endpoints are the same for both MVC and Feature architectures.

Authentication Routes

Base URL: `http://localhost:9000/api/v1/auth`

Method	Endpoint	Description
POST	/signup	Register new user and send verification OTP
POST	/verify-user	Verify email with OTP
POST	/signin	Login user and set auth cookies
GET	/profile	Get current user profile
PATCH	/profile	Update profile and avatar
GET	/sessions	List active sessions
DELETE	/sessions	Revoke all sessions except current
DELETE	/sessions/:sessionId	Revoke a specific session
POST	/refresh-token	Rotate access and refresh tokens
POST	/logout	Logout current session
POST	/forgot-password	Request password reset OTP
POST	/verify-reset-otp	Verify password reset OTP
POST	/reset-password	Reset password after OTP verification
POST	/change-password	Change password and revoke sessions
POST	/account/request-delete	Request account deletion token
DELETE	/account/delete	Delete or deactivate account by token
PUT	/account/reactivate	Reactivate soft-deleted account

OAuth Routes

Base URL: `http://localhost:9000/api/auth`

Method	Endpoint	Description
GET	/github	Initiate GitHub OAuth
GET	/github/callback	GitHub OAuth callback
GET	/google	Initiate Google OAuth
GET	/google/callback	Google OAuth callback
GET	/facebook	Initiate Facebook OAuth
GET	/facebook/callback	Facebook OAuth callback

Health Check

Base URL: `http://localhost:9000/api/v1/health`

Method	Endpoint	Description
GET	/	Basic health check
GET	/detailed	Detailed health status

Environment Variables

Create a .env file with the following:

PORT='9000'
NODE_ENV='development'
LOG_LEVEL='info'
CORS_ORIGIN=''
CLIENT_URL=''
 
DATABASE_URL=''
REDIS_URL=''
 
JWT_ACCESS_SECRET=''
JWT_REFRESH_SECRET=''
CRYPTO_SECRET=''
 
RESEND_API_KEY=''
EMAIL_FROM=''
 
CLOUDINARY_CLOUD_NAME=''
CLOUDINARY_API_KEY=''
CLOUDINARY_API_SECRET=''
 
GOOGLE_CLIENT_ID=''
GOOGLE_CLIENT_SECRET=''
GOOGLE_REDIRECT_URI=''
 
GITHUB_CLIENT_ID=''
GITHUB_CLIENT_SECRET=''
GITHUB_REDIRECT_URI=''
 
FACEBOOK_APP_ID=''
FACEBOOK_APP_SECRET=''
FACEBOOK_REDIRECT_URI=''