# Auth Flow Validation > Authentication flow validation between frontend and backend. Covers JWT, OAuth2, token refresh, and session management sync. USE WHEN: user asks about "auth integration", "JWT validation", "token refresh", "401 handling", "authentication flow", "login integration" DO NOT USE FOR: security auditing - use security skills, OAuth provider setup - use authentication skills - Skill: `claude-dev-suite/auth-flow-validation` (Agent Skill) - Install (CLI): `npx skillmds@latest add claude-dev-suite/auth-flow-validation` - Raw SKILL.md: https://api.skillmd.com/api/skills/claude-dev-suite/auth-flow-validation/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: claude-dev-suite (https://skillmd.com/u/claude-dev-suite) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/claude-dev-suite/auth-flow-validation --- # Auth Flow Validation - Quick Reference ## When NOT to Use This Skill - **Security auditing** - Use `security` skills - **OAuth provider configuration** - Use `oauth2` skill - **JWT implementation** - Use `jwt` skill > **Deep Knowledge**: Use `mcp__documentation__fetch_docs` with technology: `jwt` or `oauth2` for protocol details. ## Auth Flow Overview ``` ┌─────────────────────────────────────────────────────────────────────┐ │ AUTHENTICATION FLOW │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Frontend Backend │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 1. Login │──────────→│ POST /auth │ │ │ │ Form │ │ /login │ │ │ └──────────────┘ └──────┬───────┘ │ │ ↑ │ │ │ │ ↓ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 2. Store │←──────────│ Return JWT │ │ │ │ Tokens │ │ + Refresh │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ ↓ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 3. API Call │──────────→│ Validate JWT │ │ │ │ + Auth Header│ │ │ │ │ └──────────────┘ └──────┬───────┘ │ │ ↑ │ │ │ │ 401 Unauthorized │ │ │ │←─────────────────────────┤ │ │ │ │ │ │ ↓ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ 4. Refresh │──────────→│ POST /auth │ │ │ │ Token │ │ /refresh │ │ │ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ## Validation Checklist ### Login Flow | Step | Frontend | Backend | Validation | |------|----------|---------|------------| | Endpoint | POST /auth/login | POST /auth/login | Path match | | Request Body | { email, password } | { email, password } | Schema match | | Response | { accessToken, refreshToken, user } | Same structure | Type match | | Token Storage | localStorage/httpOnly cookie | Expects cookie or header | Method match | | Error Response | Handle 401, 400 | Returns structured error | Error format | ### Token Refresh Flow | Step | Frontend | Backend | Validation | |------|----------|---------|------------| | Trigger | 401 response intercepted | Returns 401 on expired | Consistent behavior | | Endpoint | POST /auth/refresh | POST /auth/refresh | Path match | | Request | refreshToken in body/cookie | Expects same location | Method match | | Response | New accessToken | Returns new token | Structure match | | Retry | Original request retried | Accepts new token | Flow complete | ## Common Discrepancies ### 1. Token Storage Mismatch ```typescript // Backend expects: HttpOnly cookie res.cookie('accessToken', token, { httpOnly: true, secure: true, sameSite: 'strict', }); // Frontend stores: localStorage (MISMATCH!) localStorage.setItem('accessToken', response.accessToken); // Frontend should: Let backend set cookie // No manual storage needed - cookie sent automatically ``` ### 2. Authorization Header Format ```typescript // Backend expects Authorization: Bearer eyJhbGciOiJIUzI1NiIs... // Frontend sends (WRONG) Authorization: eyJhbGciOiJIUzI1NiIs... // Missing "Bearer " // Frontend sends (WRONG) Authorization: bearer eyJhbGciOiJIUzI1NiIs... // Wrong case // Correct frontend implementation const token = getAccessToken(); fetch('/api/users', { headers: { 'Authorization': `Bearer ${token}`, }, }); ``` ### 3. Refresh Token Placement ```typescript // Backend expects: Cookie app.post('/auth/refresh', (req, res) => { const refreshToken = req.cookies.refreshToken; // From cookie }); // Frontend sends: Body (MISMATCH!) fetch('/auth/refresh', { method: 'POST', body: JSON.stringify({ refreshToken }), // Wrong! }); // Correct: Cookie sent automatically fetch('/auth/refresh', { method: 'POST', credentials: 'include', // Include cookies }); ``` ### 4. Token Expiration Handling ```typescript // Backend: Token expires after 15 minutes const token = jwt.sign(payload, secret, { expiresIn: '15m' }); // Frontend: No expiration check (BAD) function makeAuthenticatedRequest() { return fetch('/api/data', { headers: { Authorization: `Bearer ${token}` }, }); } // Frontend: Check expiration before request (GOOD) function makeAuthenticatedRequest() { const token = getAccessToken(); if (isTokenExpired(token)) { await refreshAccessToken(); } return fetch('/api/data', { headers: { Authorization: `Bearer ${getAccessToken()}` }, }); } // Helper to check expiration function isTokenExpired(token: string): boolean { const payload = JSON.parse(atob(token.split('.')[1])); return payload.exp * 1000 < Date.now(); } ``` ## Token Refresh Patterns ### Axios Interceptor ```typescript import axios from 'axios'; const api = axios.create({ baseURL: '/api', }); // Request interceptor - add token api.interceptors.request.use((config) => { const token = getAccessToken(); if (token) { config.headers.Authorization = `Bearer ${token}`; } return config; }); // Response interceptor - handle 401 api.interceptors.response.use( (response) => response, async (error) => { const originalRequest = error.config; if (error.response?.status === 401 && !originalRequest._retry) { originalRequest._retry = true; try { const newToken = await refreshAccessToken(); originalRequest.headers.Authorization = `Bearer ${newToken}`; return api(originalRequest); } catch (refreshError) { // Refresh failed - logout user logout(); return Promise.reject(refreshError); } } return Promise.reject(error); } ); ``` ### Fetch with Refresh ```typescript async function fetchWithAuth(url: string, options: RequestInit = {}) { let token = getAccessToken(); // Check if token expired if (isTokenExpired(token)) { token = await refreshAccessToken(); } const response = await fetch(url, { ...options, headers: { ...options.headers, Authorization: `Bearer ${token}`, }, }); // Handle 401 (token rejected by server) if (response.status === 401) { token = await refreshAccessToken(); return fetch(url, { ...options, headers: { ...options.headers, Authorization: `Bearer ${token}`, }, }); } return response; } ``` ### React Query Auth ```typescript import { QueryClient } from '@tanstack/react-query'; const queryClient = new QueryClient({ defaultOptions: { queries: { retry: (failureCount, error) => { // Don't retry on 401 if (error instanceof Response && error.status === 401) { return false; } return failureCount < 3; }, }, }, }); // Global error handler queryClient.setDefaultOptions({ mutations: { onError: (error) => { if (error instanceof Response && error.status === 401) { // Redirect to login window.location.href = '/login'; } }, }, }); ``` ## OpenAPI Auth Definition ### JWT Bearer ```yaml components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT security: - bearerAuth: [] paths: /users: get: security: - bearerAuth: [] responses: 401: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' ``` ### Cookie Auth ```yaml components: securitySchemes: cookieAuth: type: apiKey in: cookie name: accessToken paths: /users: get: security: - cookieAuth: [] ``` ## Validation Report Template ```markdown ## Auth Flow Validation Report ### Login Flow | Check | Status | Details | |-------|--------|---------| | Endpoint path | OK | POST /auth/login | | Request body | OK | { email, password } | | Response structure | WARNING | Missing `expiresIn` field | | Token storage | ERROR | Frontend uses localStorage, backend expects cookie | ### Token Refresh Flow | Check | Status | Details | |-------|--------|---------| | Trigger condition | OK | 401 intercepted | | Refresh endpoint | OK | POST /auth/refresh | | Token placement | ERROR | Frontend sends in body, backend expects cookie | | Retry mechanism | OK | Original request retried | ### Recommendations 1. **Critical**: Change token storage to httpOnly cookies 2. **Critical**: Update refresh to use credentials: 'include' 3. **Warning**: Add expiresIn to login response for proactive refresh ``` ## Anti-Patterns | Anti-Pattern | Why It's Bad | Correct Approach | |--------------|--------------|------------------| | localStorage for tokens | XSS vulnerability | Use httpOnly cookies | | No token refresh | Poor UX, forced logout | Implement refresh flow | | Refresh on every request | Performance | Refresh on 401 or near expiry | | No logout on refresh fail | Security risk | Clear tokens and redirect | | Hardcoded token expiry | Drift with backend | Parse from token or response | ## Quick Troubleshooting | Issue | Likely Cause | Solution | |-------|--------------|----------| | 401 on login | Wrong credentials format | Check request body schema | | 401 after refresh | Refresh token also expired | Re-authenticate user | | Infinite refresh loop | Not marking retried requests | Add retry flag | | CORS on auth endpoints | Missing credentials config | Add `credentials: 'include'` | | Token not sent | Authorization header format | Check "Bearer " prefix | ## Related Skills - [OpenAPI Contract](../openapi-contract/SKILL.md) - [Error Contract](../error-contract/SKILL.md) - [JWT Security](../../security/owasp/SKILL.md)