I Built a Free Auth0 Alternative That Gives You 20+ Routes in One Line of Code

Dhruv Agnihotri — Tue, 03 Feb 2026 01:13:05 +0000

TL;DR: Open-source auth that costs $0/year (vs $2,880+ for Auth0), sets up in 2 minutes, gives you 20+ production routes in one line, and includes an industry-first "smart cookie fallback". Both packages work independently or together. I'm using it in production for my own projects.

🔗 Links: HeadlessKit Hub • React (NPM) • Flask (PyPI) • React GitHub • Flask GitHub

The Problem - Why existing solutions fall short
Meet HeadlessKit - Three architectures, one system
Architecture - How it works under the hood
2-Minute Setup - Get started instantly
What You Get - 20+ routes, complete state management
Smart Cookie Fallback - Industry-first feature
JWT-Aware Refresh - Intelligent token management
Comparison Table - vs NextAuth, Clerk, Auth0, Supabase
Production Use Cases - Real-world examples
Extensibility - Hooks, custom models, OAuth
Security - OWASP-compliant, production-ready
Get Started - Installation instructions
Roadmap - What's next

The $2,880+/Year Problem

You're building a new app. You need authentication. Your options?

Solution	Cost/Year	Setup Time	The Catch
Auth0	$2,880+	20 min	Vendor lock-in, expensive (Professional: $240/mo)
Clerk	$300+	15 min	Vendor lock-in, expensive with add-ons ($100/mo each)
NextAuth	Free	30 min	Manual backend, DIY security
Supabase	Free tier	15 min	Limited, vendor lock-in
Build it yourself	Free	2-3 weeks	JWT rotation, OAuth, MFA, password reset...

I faced this exact problem for my side projects (PDFCourt.com and ShuffleTurn.com). As an indie developer, I couldn't justify $240-300/month for basic auth. But building from scratch meant weeks of work handling JWT rotation, OAuth, token refresh, password reset flows, email verification...

So I built this library. And now I'm open-sourcing it.

What This Is

✅ MIT licensed - Use it however you want
✅ Self-hosted - Your data, your server
✅ No vendor lock-in - Standard JWT, REST APIs
✅ Battle-tested - Running my own production apps
✅ Actively maintained - I use this daily, so I keep it updated

What This Isn't

❌ Not trying to replace Auth0/Clerk for enterprises
❌ Not a VC-backed startup (just an indie dev)
❌ Not claiming thousands of users (yet!)
❌ Not promising 24/7 support

This is a tool I built for myself and am sharing with the community. If it helps you, awesome!

Meet HeadlessKit Authentication

Two packages. Three ways to use them. Zero vendor lock-in.

📦 The Packages

Frontend: @headlesskits/react-headless-auth

npm install @headlesskits/react-headless-auth

Backend: flask-headless-auth

pip install flask-headless-auth

🏗️ Three Architectures, One System

1️⃣ Full Stack (React + Flask)

Use case: New projects, rapid prototyping, maximum convenience

# Backend: One line
auth = AuthSvc(app)

// Frontend: One component
<AuthProvider config={{ apiBaseUrl: 'http://localhost:5000' }}>
  <App />
</AuthProvider>

Result: Complete auth system in 2 minutes. 20+ routes. Zero config.

2️⃣ Backend Only (Flask → Any Frontend)

Use case: You have Vue/Angular/Svelte/Mobile app, need a backend

auth = AuthSvc(app)  # 20+ REST endpoints ready

Works with:

Vue, Angular, Svelte, Solid.js
React Native, Flutter, iOS, Android
Desktop apps (Electron, Tauri)
ANY HTTP client

What you get: Production-ready REST API with JWT auth, OAuth, MFA, password reset, email verification. Just point your frontend to the endpoints.

3️⃣ Frontend Only (React → Any Backend)

Use case: You have Express/Django/FastAPI backend, need a frontend

<AuthProvider config={{ apiBaseUrl: 'https://your-api.com' }}>
  <App />
</AuthProvider>

Works with: Express, Django, FastAPI, .NET, Rails, Go, Rust...

What you need: Implement 5 simple endpoints:

POST /api/auth/login → { user, access_token, refresh_token }
POST /api/auth/signup → { user, access_token, refresh_token }
GET /api/auth/user/@me → { user }
POST /api/auth/logout → { message }
POST /api/auth/token/refresh → { access_token, refresh_token }

Bonus: The React package uses a framework-agnostic core. Import AuthClient directly for Vue, Svelte, or vanilla JS.

Architecture Overview

Understanding how HeadlessKit works under the hood helps you make informed decisions and extend it effectively.

Core Design Principles

1. Framework-Agnostic Core

┌─────────────────────────────────────────┐
│         React Layer                     │
│  AuthProvider, useAuth, hooks           │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│      Framework-Agnostic Core            │
│  AuthClient + TokenStorage              │
│  (Works with ANY framework)             │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│         Backend API                     │
│  Flask/Express/Django/FastAPI           │
└─────────────────────────────────────────┘

The React components are a thin wrapper around AuthClient, which handles all auth logic. This means:

Easy to port to Vue, Svelte, Angular
Can use directly in Node.js or React Native
Business logic stays framework-independent

Authentication Flow

Login/Signup Flow:

1. User submits credentials
   └─> AuthClient.login(email, password)
       └─> POST /api/auth/login
           └─> Backend validates credentials
               └─> Returns { user, access_token, refresh_token }
                   └─> TokenStorage detects cookie support
                       ├─> ✅ Cookies work → Store in httpOnly cookies
                       └─> ❌ Cookies blocked → Store in localStorage
                           └─> Schedule automatic token refresh
                               └─> User object stored in React Context

Token Refresh Flow:

1. AuthClient decodes JWT access_token
   └─> Reads expiry time (exp claim)
       └─> Schedules refresh 5 minutes before expiration
           └─> When time arrives:
               └─> POST /api/auth/token/refresh
                   └─> Sends refresh_token
                       └─> Backend validates & rotates tokens
                           └─> Returns new access_token + refresh_token
                               └─> Tokens updated silently (user stays logged in)

Key insight: No fixed intervals. The system reads your JWT's actual expiry and refreshes precisely when needed.

Backend Architecture (Flask)

Component Hierarchy:

┌─────────────────────────────────────────┐
│            AuthSvc                      │
│  (Main entry point - one line setup)    │
└──────────────┬──────────────────────────┘
               │
               ├─> UserManager (user CRUD, validation)
               ├─> TokenManager (JWT, refresh, blacklist)
               ├─> AuthManager (login, signup, password)
               ├─> OAuthManager (Google, Microsoft)
               └─> RBACManager (roles, permissions)

Each manager is independent and composable

Why this matters:

Want just OAuth? Import OAuthManager only
Custom user logic? Extend UserManager
Different database? Swap UserRepository

All managers follow a single-responsibility design, making the codebase maintainable and extensible.

Token Storage Strategy

Frontend Storage Decision Tree:

// On first login:
1. Try to set a test cookie
2. Try to read it back
3. If successful → use httpOnly cookies (secure)
4. If blocked → use localStorage (compatible)
5. Remember choice for session

Backend Token Management:

# Three-tier token system:
1. Access Token (short-lived, 15 min)
   └─> Used for API requests

2. Refresh Token (long-lived, 30 days)
   └─> Used to get new access tokens

3. Token Blacklist (Redis/DB)
   └─> Invalidated tokens on logout

This prevents the common problem where users with cookie blockers can't use your app, while maintaining maximum security for those who allow cookies.

State Management (React)

Context Architecture:

<AuthProvider>           // Top-level wrapper
  └─> AuthContext        // React Context
      ├─> AuthClient     // Core logic
      ├─> TokenStorage   // Storage abstraction
      └─> State:
          ├─> user (object | null)
          ├─> isAuthenticated (boolean)
          ├─> isLoading (boolean)
          └─> error (object | null)

Why Context + Core Client?

Context handles React-specific state updates
AuthClient handles framework-agnostic logic
Easy to test each layer independently
Can use AuthClient without React

Database Schema (Flask)

Minimal required schema:

users
├─ id (Primary Key)
├─ email (Unique, Indexed)
├─ password_hash
├─ email_confirmed (Boolean)
├─ mfa_enabled (Boolean)
├─ mfa_secret
├─ created_at
└─ updated_at

token_blacklist
├─ jti (JWT ID)
└─ expires_at

Extensible: Add any fields you need. The library validates that required fields exist at startup.

Security Layers

Defense in Depth:

1. Transport Layer
   └─> HTTPS, Secure cookies, SameSite attribute

2. Storage Layer
   └─> httpOnly cookies (XSS-proof) or encrypted localStorage

3. Token Layer
   └─> JWT signing, expiry, rotation, blacklisting

4. Application Layer
   └─> bcrypt hashing, rate limiting, input validation

5. Database Layer
   └─> Parameterized queries (SQLAlchemy ORM)

No single point of failure. Multiple security mechanisms protect your auth system.

Extensibility Philosophy

The architecture is designed around progressive enhancement:

Start simple - Default configuration works out of the box
Extend when needed - Add hooks, custom models, or swap components
Never locked in - Standard REST APIs and JWT tokens mean you can migrate away anytime

Every component has extension points: lifecycle hooks in the frontend, custom models in the backend, and swappable services (email, storage, database) throughout. The system uses composition over inheritance, making it easy to replace individual pieces without touching others.

See the Extensibility section below for detailed code examples and configuration options.

2-Minute Full Stack Setup

Let's see the full-stack approach in action.

Backend (10 lines = 20+ routes)

from flask import Flask
from flask_headless_auth import AuthSvc

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key'
app.config['JWT_SECRET_KEY'] = 'jwt-secret-key'
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'

# THIS IS THE MAGIC LINE 🪄
auth = AuthSvc(app)

if __name__ == '__main__':
    app.run()

Frontend (Complete auth in 3 lines)

import { AuthProvider, useAuth } from '@headlesskits/react-headless-auth';

// 1. Wrap your app
<AuthProvider config={{ apiBaseUrl: 'http://localhost:5000' }}>
  <App />
</AuthProvider>

// 2. Use anywhere in your components
function MyComponent() {
  const { user, login, logout, isAuthenticated } = useAuth();

  return (
    <div>
      {isAuthenticated ? (
        <>
          <h1>Welcome {user.email}!</h1>
          <button onClick={logout}>Logout</button>
        </>
      ) : (
        <button onClick={() => login(email, password)}>Login</button>
      )}
    </div>
  );
}

That's it! Full authentication in less than 50 lines total.

⚡ What You Get Instantly

Backend: 20+ Production-Ready Routes

One line of code (auth = AuthSvc(app)) gives you:

Core Authentication:

✅ POST /api/auth/signup - User registration with validation
✅ POST /api/auth/login - JWT authentication
✅ POST /api/auth/logout - Token blacklisting
✅ GET /api/auth/user/@me - Get current user
✅ POST /api/auth/token/refresh - Automatic token refresh

OAuth Providers:

✅ GET /api/auth/login/google - Google OAuth
✅ GET /api/auth/login/microsoft - Microsoft OAuth
✅ GET /api/auth/callback/google - OAuth callback handling
✅ GET /api/auth/callback/microsoft - OAuth callback handling

Password Management:

✅ POST /api/auth/password/update - Change password
✅ POST /api/auth/request-password-reset - Initiate reset flow
✅ POST /api/auth/reset-password/<token> - Complete password reset
✅ POST /api/auth/validate-reset-token - Verify reset token

Email & Verification:

✅ GET /api/auth/confirm/<token> - Email verification
✅ POST /api/auth/resend-confirmation - Resend verification email

Multi-Factor Authentication:

✅ POST /api/auth/mfa/enable - Enable 2FA
✅ POST /api/auth/mfa/verify - Verify 2FA code
✅ POST /api/auth/mfa/disable - Disable 2FA

User Management:

✅ GET /api/auth/users - List users (admin)
✅ DELETE /api/auth/user/<id> - Delete user (admin)
✅ PUT /api/auth/user/<id> - Update user

📖 See full API documentation

Frontend: Complete Auth State Management

const {
  // User data
  user,                    // Current user object
  isAuthenticated,         // Boolean auth state
  isLoading,              // Loading state

  // Actions
  login,                  // (email, password) => Promise
  signup,                 // (email, password) => Promise
  logout,                 // () => Promise
  updatePassword,         // (old, new) => Promise

  // Token management
  refreshToken,           // Manual refresh (auto-handled)

  // Error handling
  error                   // Last error object
} = useAuth();

Additional hooks:

// Just the user data
const user = useUser();

// Just the session state
const { isAuthenticated, isLoading } = useSession();

Security: Production-Ready, Zero Config

All of this comes built-in, no configuration needed:

✅ httpOnly cookies - XSS-proof token storage
✅ bcrypt hashing - Password hashing (cost factor 12)
✅ JWT rotation - Automatic token refresh & rotation
✅ Token blacklisting - Invalidate tokens on logout
✅ CSRF protection - SameSite cookies
✅ Rate limiting - Prevent brute force attacks
✅ Input validation - SQL injection & XSS prevention
✅ Secure password reset - Time-limited tokens

Secure by default. No security expertise required.

🏆 Innovation #1: Smart Cookie Fallback

Here's a feature I'm particularly proud of.

The Problem Other Libraries Have

Most auth libraries force you to choose:

Cookies (most secure, httpOnly, XSS-proof) OR
localStorage (works when cookies blocked, but vulnerable to XSS)

Result: 1-2% of users with strict privacy settings get "Please enable cookies" errors and can't use your app.

My Solution: Intelligent Fallback

HeadlessKit uses BOTH automatically:

┌─────────────────────────────────────────┐
│         User logs in                    │
└──────────────┬──────────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │ Test cookie support  │
    │ (automatic, silent)  │
    └──────────┬───────────┘
               │
       ┌───────┴────────┐
       │                │
    ✅ YES            ❌ NO
       │                │
       ▼                ▼
┌──────────────┐  ┌────────────────┐
│ httpOnly     │  │ localStorage   │
│ Cookies      │  │ Fallback       │
│              │  │                │
│ 99% of users │  │ 1% of users    │
│ XSS-proof ✅ │  │ Still works ⚠️ │
└──────────────┘  └────────────────┘

The Result

✅ 99% of users get maximum security (httpOnly cookies)
✅ 1% with blocked cookies still have a working app (localStorage)
✅ Zero configuration needed
✅ Automatic detection - happens silently on first login
✅ No error screens - no "please enable cookies" messages
✅ Graceful degradation - best security available for each user

Why This Matters

Most libraries either:

Use cookies only (breaks for 1-2% of users with strict privacy settings)
Use localStorage only (less secure for everyone)
Make you choose (adds complexity)

This approach: Best security for each user, automatically.

🧠 Innovation #2: JWT-Aware Token Refresh

Most libraries refresh tokens on a fixed interval (e.g., every 50 minutes). This is inefficient and can cause issues.

The Smart Approach

HeadlessKit decodes your JWT, reads the actual expiry time, and schedules refresh exactly when needed:

// Inside AuthClient.ts
private scheduleTokenRefresh(token: string): void {
  const payload = this.decodeJWT(token);

  if (payload?.exp) {
    // JWT has expiry - refresh 5 min before expiration
    const expiryTime = payload.exp * 1000;
    const refreshTime = expiryTime - (5 * 60 * 1000);
    const delay = Math.max(0, refreshTime - Date.now());

    this.refreshTimeoutId = setTimeout(async () => {
      await this.refreshToken();
    }, delay);
  }
}

Benefits

✅ Precise timing - refreshes exactly when needed
✅ No wasted requests - doesn't refresh too early
✅ Seamless UX - users stay logged in without interruption
✅ Respects your backend - uses the expiry time YOU set
✅ Works with any JWT - reads standard exp claim

📊 The Comparison

Feature	HeadlessKit	NextAuth	Clerk	Auth0	Supabase
Setup Time	⚡ 2 minutes	30 min	15 min	20 min	15 min
Monthly Cost	✅ $0	Free	$25-325+	$240+	Free tier limited
Annual Cost	✅ $0	Free	$300-3,900+	$2,880+	Scales with usage
Smart Cookie Fallback	✅ Yes	❌	❌	❌	❌
Works Independently	✅ Mix & Match	⚠️ Backend DIY	❌	❌	⚠️ Complex
One-Line Backend	✅ AuthSvc(app)	❌ DIY	✅	✅	✅
Custom User Models	✅ With validation	✅	❌	❌	⚠️ Limited
Self-Hosted	✅ Full control	✅	❌	❌	⚠️ Complex
Bundle Size	✅ 15KB	❌ Heavy	✅ Small	✅ Small	⚠️ Medium
JWT-Aware Refresh	✅ Smart	⚠️ Manual	✅	✅	✅
Vendor Lock-in	✅ None	✅ None	❌ High	❌ High	⚠️ Medium
OAuth Providers	✅ Google, MS	✅ Many	✅ Many	✅ Many	✅ Many
MFA/2FA	✅ Built-in	⚠️ Manual	✅	✅	✅
Email Verification	✅ Built-in	⚠️ Manual	✅	✅	✅
RBAC	✅ Built-in	⚠️ Manual	✅	✅	✅

💼 How I'm Using This in Production

I built this library because I needed it for my own projects. Here's how I'm using it:

PDFCourt.com - Legal Document Processing

Custom user model with subscription tiers
Quota tracking per user
Self-hosted for data compliance

class User(db.Model, UserMixin):
    subscription_tier = db.Column(db.String(50), default='free')
    documents_processed = db.Column(db.Integer, default=0)
    monthly_limit = db.Column(db.Integer, default=10)

auth = AuthSvc(app, user_model=User)

@app.route('/api/auth/check-quota')
@jwt_required()
def check_quota():
    user = User.query.get(get_jwt_identity())
    remaining = user.monthly_limit - user.documents_processed
    return {'remaining': remaining, 'can_process': remaining > 0}

ShuffleTurn.com - Gaming Platform

OAuth integration (Google, Microsoft)
Analytics integration via lifecycle hooks
Custom user fields for gaming stats

<AuthProvider
  config={{ apiBaseUrl: 'https://api.shuffleturn.com' }}
  hooks={{
    afterLogin: ({ user }) => {
      posthog.identify(user.id, {
        username: user.username,
        level: user.level
      });
    },
    transformUser: ({ user }) => ({
      ...user,
      rankTitle: getRankTitle(user.level),
      isPro: user.level >= 50
    })
  }}
>
  <App />
</AuthProvider>

Why I'm confident sharing this: I'm using this exact code in production. If it works for my projects, it can work for yours.

🎨 When You Need More: Extensibility

Start simple. Extend when needed. Here's how:

1. Lifecycle Hooks (Frontend)

Inject custom logic at any point in the auth flow:

<AuthProvider
  config={{ apiBaseUrl: 'http://localhost:5000' }}
  hooks={{
    // After successful login
    afterLogin: ({ user }) => {
      analytics.identify(user.id);
      posthog.track('User Logged In');
    },

    // On login error
    onLoginError: ({ error }) => {
      Sentry.captureException(error);
      toast.error(error.message);
    },

    // After successful signup
    afterSignup: ({ user }) => {
      analytics.track('User Signed Up');
      // Trigger onboarding flow
    },

    // Transform user data
    transformUser: ({ user }) => ({
      ...user,
      fullName: `${user.first_name} ${user.last_name}`,
      isAdmin: user.roles?.includes('admin')
    }),

    // After token refresh
    afterTokenRefresh: ({ access_token }) => {
      console.log('Token refreshed silently');
    },

    // After logout
    afterLogout: () => {
      analytics.reset();
      // Clear app state
    },

    // Global auth error handler
    onAuthError: ({ error }) => {
      if (error.status === 401) {
        // Redirect to login
      }
    }
  }}
>
  <App />
</AuthProvider>

Available hooks:

afterLogin - Post-login logic
afterSignup - Post-signup logic
afterLogout - Post-logout cleanup
onLoginError - Login error handling
onSignupError - Signup error handling
afterTokenRefresh - Token refresh callback
transformUser - Transform user data
onAuthError - Global error handler

Perfect for:

Analytics (PostHog, Mixpanel, Amplitude)
Error tracking (Sentry, LogRocket)
Onboarding flows
Data transformation
Custom redirects

2. Custom User Models (Backend)

Add any fields you need to the user model:

from flask_headless_auth import AuthSvc, UserMixin

class User(db.Model, UserMixin):
    __tablename__ = 'users'

    # Add ANY custom fields
    company = db.Column(db.String(200))
    subscription_tier = db.Column(db.String(50), default='free')
    monthly_quota = db.Column(db.Integer, default=100)
    username = db.Column(db.String(50), unique=True)
    level = db.Column(db.Integer, default=1)
    avatar_url = db.Column(db.String(500))
    bio = db.Column(db.Text)
    preferences = db.Column(db.JSON)

auth = AuthSvc(app, user_model=User)

Bonus: Model Validation

We validate your model at startup. Missing required fields? You get a clear error with the exact fix:

❌ USER MODEL VALIDATION FAILED

Missing required field: mfa_enabled
Type: Boolean
Default: False

SQL Fix:
ALTER TABLE users ADD COLUMN mfa_enabled BOOLEAN DEFAULT FALSE;

No cryptic runtime errors in production!

3. Custom JWT Claims

Add custom data to JWT tokens:

@auth.additional_claims_loader
def add_claims_to_jwt(identity):
    user = User.query.get(identity)
    return {
        'role': user.role,
        'subscription': user.subscription_tier,
        'company_id': user.company_id,
        'permissions': user.get_permissions()
    }

Access in protected routes:

from flask_jwt_extended import get_jwt

@app.route('/api/admin/users')
@jwt_required()
def admin_users():
    claims = get_jwt()

    if claims.get('role') != 'admin':
        return {'error': 'Unauthorized'}, 403

    # Admin logic here

4. Custom Routes & Endpoints

Add your own protected endpoints:

from flask_jwt_extended import jwt_required, get_jwt_identity

auth = AuthSvc(app)

@app.route('/api/auth/check-quota')
@jwt_required()
def check_quota():
    user_id = get_jwt_identity()
    user = User.query.get(user_id)

    if user.subscription_tier == 'free' and user.usage > 100:
        return {'error': 'Upgrade required'}, 403

    return {'remaining': user.monthly_quota - user.usage}

@app.route('/api/auth/upgrade')
@jwt_required()
def upgrade_subscription():
    user_id = get_jwt_identity()
    user = User.query.get(user_id)

    user.subscription_tier = 'pro'
    user.monthly_quota = 1000
    db.session.commit()

    return {'message': 'Upgraded successfully'}

5. Framework-Agnostic Core (No React Required)

Use the core AuthClient with any framework:

import { AuthClient, TokenStorage } from '@headlesskits/react-headless-auth/core';

// Initialize
const storage = new TokenStorage('cookie-first');
const authClient = new AuthClient(
  { apiBaseUrl: 'https://api.example.com' },
  storage
);

// Use anywhere
await authClient.login(email, password);
const user = await authClient.getUser();
await authClient.logout();

Works in:

✅ Vue 3, Svelte, Angular, Solid.js
✅ React Native (with AsyncStorage adapter)
✅ Electron (with secure storage)
✅ Vanilla JavaScript
✅ Node.js (server-side)

Example: Vue 3 Composition API

import { ref, onMounted } from 'vue';
import { AuthClient, TokenStorage } from '@headlesskits/react-headless-auth/core';

export function useAuth() {
  const user = ref(null);
  const isAuthenticated = ref(false);

  const storage = new TokenStorage('cookie-first');
  const authClient = new AuthClient({ apiBaseUrl: '...' }, storage);

  const login = async (email: string, password: string) => {
    const result = await authClient.login(email, password);
    user.value = result.user;
    isAuthenticated.value = true;
  };

  onMounted(async () => {
    try {
      user.value = await authClient.getUser();
      isAuthenticated.value = true;
    } catch {
      isAuthenticated.value = false;
    }
  });

  return { user, isAuthenticated, login };
}

6. Email Service Configuration

Built-in support for Gmail and Brevo (SendInBlue):

# Gmail
app.config['EMAIL_SERVICE'] = 'gmail'
app.config['GMAIL_ADDRESS'] = 'your-email@gmail.com'
app.config['GMAIL_APP_PASSWORD'] = 'your-app-password'

# OR Brevo
app.config['EMAIL_SERVICE'] = 'brevo'
app.config['BREVO_API_KEY'] = 'your-api-key'
app.config['BREVO_SENDER_EMAIL'] = 'noreply@yourdomain.com'
app.config['BREVO_SENDER_NAME'] = 'Your App'

auth = AuthSvc(app)

Or bring your own email service:

from flask_headless_auth.interfaces import EmailServiceInterface

class CustomEmailService(EmailServiceInterface):
    def send_email(self, to: str, subject: str, body: str):
        # Your email logic here
        pass

auth = AuthSvc(app, email_service=CustomEmailService())

7. OAuth Provider Configuration

Add Google and Microsoft OAuth:

# Google OAuth
app.config['GOOGLE_CLIENT_ID'] = 'your-google-client-id'
app.config['GOOGLE_CLIENT_SECRET'] = 'your-google-client-secret'
app.config['GOOGLE_REDIRECT_URI'] = 'http://localhost:5000/api/auth/callback/google'

# Microsoft OAuth
app.config['MICROSOFT_CLIENT_ID'] = 'your-microsoft-client-id'
app.config['MICROSOFT_CLIENT_SECRET'] = 'your-microsoft-client-secret'
app.config['MICROSOFT_REDIRECT_URI'] = 'http://localhost:5000/api/auth/callback/microsoft'

auth = AuthSvc(app)

Frontend usage:

function LoginPage() {
  const handleGoogleLogin = () => {
    window.location.href = 'http://localhost:5000/api/auth/login/google';
  };

  return (
    <button onClick={handleGoogleLogin}>
      Sign in with Google
    </button>
  );
}

🔒 Security Deep Dive

What's Included Out of the Box

Password Security:

bcrypt hashing with cost factor 12
Minimum password requirements (8+ chars, uppercase, lowercase, number)
Password strength validation
Secure password reset with time-limited tokens

Token Security:

JWT with RS256 or HS256 signing
Automatic token rotation
Token blacklisting on logout
Refresh token rotation
httpOnly cookies (XSS-proof)
SameSite cookie attribute (CSRF protection)

API Security:

Rate limiting on auth endpoints (10 requests/minute)
Input validation and sanitization
SQL injection prevention (SQLAlchemy ORM)
CORS configuration support
Request size limits

Session Security:

Automatic session timeout
Concurrent session management
Device tracking (optional)
IP-based validation (optional)

Security Best Practices

The library follows OWASP guidelines:

✅ A01: Broken Access Control - JWT-based auth with role validation
✅ A02: Cryptographic Failures - bcrypt, secure token generation
✅ A03: Injection - Parameterized queries, input validation
✅ A04: Insecure Design - Secure by default configuration
✅ A05: Security Misconfiguration - Sensible defaults
✅ A07: Identification and Authentication Failures - MFA support, secure password reset

🚀 Get Started in 2 Minutes

Option 1: Full Stack (React + Flask)

Step 1: Install packages

# Backend
pip install flask-headless-auth

# Frontend
npm install @headlesskits/react-headless-auth

Step 2: Backend setup

from flask import Flask
from flask_headless_auth import AuthSvc

app = Flask(__name__)
app.config['SECRET_KEY'] = 'your-secret-key'
app.config['JWT_SECRET_KEY'] = 'jwt-secret-key'
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'

auth = AuthSvc(app)

if __name__ == '__main__':
    app.run()

Step 3: Frontend setup

import { AuthProvider, useAuth } from '@headlesskits/react-headless-auth';

function App() {
  return (
    <AuthProvider config={{ apiBaseUrl: 'http://localhost:5000' }}>
      <YourApp />
    </AuthProvider>
  );
}

Done! You have full authentication.

Option 2: Backend Only

pip install flask-headless-auth

from flask import Flask
from flask_headless_auth import AuthSvc

app = Flask(__name__)
# ... config ...

auth = AuthSvc(app)  # 20+ REST endpoints ready

Point your frontend (Vue, Angular, mobile app) to the API endpoints.

Option 3: Frontend Only

npm install @headlesskits/react-headless-auth

<AuthProvider config={{ apiBaseUrl: 'https://your-backend.com' }}>
  <App />
</AuthProvider>

Implement 5 endpoints on your backend (Express, Django, etc.).

📚 Documentation & Resources

🏠 HeadlessKit Hub - Start here! All packages in one place
🌟 React Package (GitHub)
🐍 Flask Package (GitHub)
📦 React (NPM)
🐍 Flask (PyPI)
💬 Discussions
🐛 Report Issues
📧 Email Me

🗺️ Roadmap

Coming soon:

Vue.js & Svelte SDKs
Magic links (passwordless auth)
WebAuthn/Passkeys support
Express.js & FastAPI backends
React Native & Flutter SDKs
GitHub & Apple OAuth
Admin dashboard UI

Want to contribute? Check out CONTRIBUTING.md

🌟 Join the Community

If this helps you, please:

⭐ Star the repos on GitHub
🐛 Report issues or suggest features
💬 Join Discussions
🔄 Share on Twitter/X, LinkedIn, or Reddit

Dhruvagnihotri / react-headless-auth

@headlesskits/react-headless-auth

🚀 Production-ready React authentication in 2 minutes. Smart cookie fallback, automatic token refresh, zero dependencies. The simplest way to add enterprise-grade auth to your React app.

npm install @headlesskits/react-headless-auth

💡 Why Choose This?

The Problem: Authentication is hard. Auth0 costs $300/month. Building it yourself takes weeks. Most libraries force you to choose between security (cookies) OR compatibility (localStorage).

Our Solution: Best of both worlds. Maximum security for 99% of users (httpOnly cookies), automatic fallback for the 1% with blocked cookies (localStorage). Plus a complete backend SDK so you don't spend weeks building auth routes.

Feature	react-headless-auth	NextAuth	Clerk	Auth0	Supabase Auth
Setup Time	⚡ 2 minutes	30 min	15 min	20 min	15 min
Monthly Cost	✅ $0	Free	$300	$240	Free tier limited
Smart Cookie Fallback	✅ Industry First	❌	❌	❌	❌
Zero Dependencies	✅ (~15KB)	❌ (heavy)	✅	✅	⚠️ (medium)
Backend Included	✅ flask-headless-auth	⚠️

…

View on GitHub

Dhruvagnihotri / flask-headless-auth

Flask-Headless-Auth

🔐 Production-ready Flask authentication in one line. Get 20+ auth routes instantly. JWT, OAuth, MFA, RBAC built-in. Works with React, Next.js, Vue, any frontend. The free, self-hosted alternative to Auth0/Clerk ($3,600/year saved).

💡 What You Get

In one line of code (AuthSvc(app)), you get a complete authentication system that would take weeks to build:

auth = AuthSvc(app)  # That's it! 🎉

Instantly Available:

✅ 20+ Production Routes - Login, signup, OAuth, password reset, MFA, profile management
✅ JWT + httpOnly Cookies - Maximum security with automatic fallback
✅ OAuth Ready - Google & Microsoft sign-in (GitHub, Apple coming soon)
✅ MFA/2FA - Multi-factor authentication built-in
✅ RBAC - Role-based access control
✅ Email Services - Verification & password reset emails
✅ Rate Limiting - Brute force protection
✅ Token Blacklisting - Secure logout
✅ Security Headers - CSRF, XSS, CORS protection
✅ Custom User…

View on GitHub

Your support helps other developers discover this project!

🎯 Final Thoughts

Authentication doesn't have to be hard, expensive, or lock you into a vendor. With HeadlessKit, you get:

✅ Production-ready auth in 2 minutes
✅ Smart cookie fallback for maximum compatibility
✅ 20+ routes from one line of code
✅ Complete control over your data
✅ Zero recurring costs

Built by an indie dev for indie devs. No venture capital. No pricing tiers. No vendor lock-in. Just great open-source software.

Questions? Comments? Want to contribute?

Drop a comment below or reach out on GitHub!

Tags: #react #authentication #opensource #flask #jwt #oauth #webdev #javascript #python #nextjs #security #selfhosted #indiedev #auth0alternative #clerkalt

DEV Community: Dhruv Agnihotri

I Built a Free Auth0 Alternative That Gives You 20+ Routes in One Line of Code

Table of Contents

The $2,880+/Year Problem

What This Is

What This Isn't

Meet HeadlessKit Authentication

📦 The Packages

🏗️ Three Architectures, One System

1️⃣ Full Stack (React + Flask)

2️⃣ Backend Only (Flask → Any Frontend)

3️⃣ Frontend Only (React → Any Backend)

Architecture Overview

Core Design Principles

Authentication Flow

Backend Architecture (Flask)

Token Storage Strategy

State Management (React)

Database Schema (Flask)

Security Layers

Extensibility Philosophy

2-Minute Full Stack Setup

Backend (10 lines = 20+ routes)

Frontend (Complete auth in 3 lines)

⚡ What You Get Instantly

Backend: 20+ Production-Ready Routes

Frontend: Complete Auth State Management

Security: Production-Ready, Zero Config

🏆 Innovation #1: Smart Cookie Fallback

The Problem Other Libraries Have

My Solution: Intelligent Fallback

The Result

Why This Matters

🧠 Innovation #2: JWT-Aware Token Refresh

The Smart Approach

Benefits

📊 The Comparison

💼 How I'm Using This in Production

PDFCourt.com - Legal Document Processing

ShuffleTurn.com - Gaming Platform

🎨 When You Need More: Extensibility

1. Lifecycle Hooks (Frontend)

2. Custom User Models (Backend)

3. Custom JWT Claims

4. Custom Routes & Endpoints

5. Framework-Agnostic Core (No React Required)

6. Email Service Configuration

7. OAuth Provider Configuration

🔒 Security Deep Dive

What's Included Out of the Box

Security Best Practices

🚀 Get Started in 2 Minutes

Option 1: Full Stack (React + Flask)

Option 2: Backend Only

Option 3: Frontend Only

📚 Documentation & Resources

🗺️ Roadmap

🌟 Join the Community

Dhruvagnihotri / react-headless-auth

@headlesskits/react-headless-auth

💡 Why Choose This?

Dhruvagnihotri / flask-headless-auth

Flask-Headless-Auth

💡 What You Get

🎯 Final Thoughts