Authentication System Overview

Complete guide to the Advantch authentication system using django-allauth headless with Next.js frontend

Authentication System Overview

Architecture

The authentication system uses django-allauth headless as the backend provider with a Next.js frontend. The system supports both session-based authentication (browser flow) and JWT tokens (app/mobile flow).

Core Components

Layer	Technology	Purpose
Backend	django-allauth 65.x	Authentication provider
API	Allauth Headless API	JSON API at `/_allauth/`
Frontend	Next.js + Zustand	React SPA with state management
Session	Django Sessions / JWT	Token strategy (configurable)

API Endpoints

All authentication endpoints are served at /_allauth/:

Browser clients: /_allauth/browser/v1/* — Uses cookies + CSRF tokens
App clients: /_allauth/app/v1/* — Uses JWT access/refresh tokens

Authentication Flow

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Next.js App   │ ──▶  │  Django Backend │ ──▶  │    Database     │
│  (authClient)   │      │ (allauth headless)     │  (PostgreSQL)   │
└─────────────────┘      └─────────────────┘      └─────────────────┘
        │                         │
        │  POST /auth/login       │
        │  ─────────────────────▶ │
        │                         │
        │  Set-Cookie: sessionid  │
        │  Set-Cookie: csrftoken  │
        │  ◀───────────────────── │
        │                         │
        │  GET /api/v1/users/     │
        │  Cookie: sessionid      │
        │  X-CSRFToken: ...       │
        │  ─────────────────────▶ │

Token Strategies

Session Token Strategy (Default)

For browser-based clients. Uses Django session cookies with CSRF protection.

Endpoints: /_allauth/browser/v1/*
Auth header: None (uses cookies)
CSRF: Required via X-CSRFToken header

JWT Token Strategy (Optional)

For mobile/app clients. Enable via environment variable.

HEADLESS_TOKEN_STRATEGY=allauth.headless.tokens.strategies.jwt.JWTTokenStrategy

Endpoints: /_allauth/app/v1/*
Auth header: Authorization: Bearer <access_token>
CSRF: Not required

JWT tokens include tenant claims for multitenancy:

tenant_id — Primary tenant ID
current_tenant_id — Currently active tenant

Configuration

Backend Settings

# config/settings.py

# Core allauth settings
ACCOUNT_AUTHENTICATION_METHOD = "email"
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = "mandatory"
ACCOUNT_USERNAME_REQUIRED = False
ACCOUNT_CONFIRM_EMAIL_ON_GET = True
ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION = True

# Headless mode
HEADLESS_ONLY = False  # Set True to disable legacy Django views
HEADLESS_CLIENTS = ("app", "browser")
HEADLESS_FRONTEND_URLS = {
    "account_confirm_email": "{FRONTEND_URL}/auth/verify-email/{key}",
    "account_reset_password_from_key": "{FRONTEND_URL}/auth/reset-password/{key}",
    ...
}

# Token strategy
HEADLESS_TOKEN_STRATEGY = "allauth.headless.tokens.strategies.sessions.SessionTokenStrategy"

Frontend Configuration

// lib/api-client.ts

// Auth API instance for allauth endpoints
export const authClient = Axios.create({
  baseURL: `${API_BASE_URL}/_allauth/browser/v1`,
  withCredentials: true,
  headers: {
    "Content-Type": "application/json",
  },
});

Security Features

CSRF Protection: All browser endpoints require CSRF token
Email Verification: Mandatory before account access
Password Validation: Django's default validators
Email Domain Blacklist: Blocks disposable email domains
MFA Support: TOTP, WebAuthn, and recovery codes

Login Methods — Password, magic link, social auth
Mobile Authentication — JWT flow for mobile apps
Multi-Factor Authentication — TOTP and WebAuthn setup
Social Providers — OAuth configuration

Authentication System Overview

On this page