✨ Add dual token location pattern documentation and example (#786)

- Introduced a new section in the documentation detailing the dual location pattern for access and refresh tokens.
- Added example code for implementing access tokens in headers and refresh tokens in HTTP-only cookies.
- Created a new example script demonstrating the complete flow of login, token retrieval, refresh, and logout using this pattern.

Author: yezz123

docs/get-started/location.md

@@ -253,6 +253,133 @@ config = AuthXConfig(
 
 AuthX will check each location in order until it finds a token.
 
+---
+
+## Dual Location Pattern (Access in Header, Refresh in Cookie)
+
+A common and secure pattern for web applications is to use different locations for different token types:
+
+- **Access tokens** in headers: Short-lived, stored in client memory, sent explicitly
+- **Refresh tokens** in HTTP-only cookies: Long-lived, secure storage, sent automatically
+
+!!! tip "Why This Pattern?"
+    - **Access tokens in memory**: Prevents XSS from stealing long-lived tokens
+    - **Refresh tokens in HTTP-only cookies**: Cannot be accessed by JavaScript, automatic CSRF protection
+    - **Headers for API calls**: Standard REST pattern, works with any client
+
+### Configuration
+
+```python
+from authx import AuthX, AuthXConfig
+
+config = AuthXConfig(
+    JWT_SECRET_KEY="your-secret-key",
+    JWT_TOKEN_LOCATION=["headers", "cookies"],  # Enable both
+    # Cookie settings for refresh token security
+    JWT_COOKIE_SECURE=True,         # HTTPS only (set False for local dev)
+    JWT_COOKIE_HTTP_ONLY=True,      # Prevent JS access
+    JWT_COOKIE_CSRF_PROTECT=True,   # CSRF protection for refresh
+)
+auth = AuthX(config=config)
+```
+
+### Login Endpoint
+
+```python
+@app.post("/login")
+def login(user: LoginRequest, response: Response):
+    # Validate credentials...
+
+    # Create both tokens
+    access_token = auth.create_access_token(uid=user.username)
+    refresh_token = auth.create_refresh_token(uid=user.username)
+
+    # Set ONLY refresh token in cookie
+    auth.set_refresh_cookies(refresh_token, response)
+
+    # Return access token in response body
+    return {"access_token": access_token, "token_type": "bearer"}
+```
+
+### Protected Endpoints (Access Token from Header)
+
+```python
+@app.get("/protected")
+async def protected(request: Request):
+    # Explicitly get token from headers only
+    access_token = await auth.get_access_token_from_request(
+        request,
+        locations=["headers"],  # Only look in headers
+    )
+    payload = auth.verify_token(access_token, verify_csrf=False)
+    return {"user": payload.sub}
+```
+
+### Refresh Endpoint (Refresh Token from Cookie)
+
+```python
+@app.post("/refresh")
+async def refresh(request: Request):
+    # Get refresh token from cookies only
+    refresh_token = await auth.get_refresh_token_from_request(
+        request,
+        locations=["cookies"],  # Only look in cookies
+    )
+    payload = auth.verify_token(refresh_token)
+
+    # Return new access token in body
+    new_access_token = auth.create_access_token(uid=payload.sub)
+    return {"access_token": new_access_token, "token_type": "bearer"}
+```
+
+### Logout Endpoint
+
+```python
+@app.post("/logout")
+def logout(response: Response):
+    # Clear refresh token cookie
+    auth.unset_refresh_cookies(response)
+    return {"message": "Logged out"}
+```
+
+### Client-Side Flow
+
+=== "JavaScript"
+    ```javascript
+    // Login - store access token in memory
+    const response = await fetch("/login", {
+      method: "POST",
+      credentials: "include",  // Required for cookies
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ username, password })
+    });
+    const { access_token } = await response.json();
+
+    // Store in memory (NOT localStorage)
+    let accessToken = access_token;
+
+    // API calls - send access token in header
+    await fetch("/protected", {
+      headers: { "Authorization": `Bearer ${accessToken}` }
+    });
+
+    // Refresh - cookie sent automatically
+    function getCsrfToken() {
+      return document.cookie.match(/csrf_refresh_token=([^;]+)/)?.[1];
+    }
+
+    const refreshResponse = await fetch("/refresh", {
+      method: "POST",
+      credentials: "include",
+      headers: { "X-CSRF-TOKEN": getCsrfToken() }
+    });
+    accessToken = (await refreshResponse.json()).access_token;
+    ```
+
+See the [dual_token_location.py example](https://github.com/yezz123/authx/blob/main/examples/examples/dual_token_location.py) for a complete implementation.
+
+---
+
 ## Cookie Configuration Reference
 
 | Setting | Default | Description |

examples/examples/dual_token_location.py

@@ -0,0 +1,222 @@
+"""Dual Token Location Example - Access Token in Header, Refresh Token in Cookie.
+
+This example demonstrates a common and secure pattern for web applications:
+- Access tokens (short-lived) are sent via Authorization header
+- Refresh tokens (long-lived) are stored in HTTP-only cookies
+
+Benefits of this approach:
+- Access tokens in headers: Standard for APIs, works with any client, no CSRF concerns
+- Refresh tokens in cookies: Secure storage, HTTP-only prevents XSS theft, automatic sending
+
+Flow:
+1. Login: Returns access_token in response body, sets refresh_token as HTTP-only cookie
+2. API calls: Client sends access_token in Authorization header
+3. Refresh: Client calls /refresh, refresh_token is sent automatically via cookie
+4. Logout: Server clears the refresh_token cookie
+"""
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from pydantic import BaseModel
+
+from authx import AuthX, AuthXConfig
+
+# Create a FastAPI app
+app = FastAPI(title="AuthX Dual Token Location Example")
+
+# Configure AuthX for dual token locations
+auth_config = AuthXConfig(
+    JWT_ALGORITHM="HS256",
+    JWT_SECRET_KEY="your-secret-key",  # In production, use a secure key from environment variables
+    # Enable both locations - we'll specify which to use per-endpoint
+    JWT_TOKEN_LOCATION=["headers", "cookies"],
+    # Header settings for access tokens
+    JWT_HEADER_NAME="Authorization",
+    JWT_HEADER_TYPE="Bearer",
+    # Cookie settings for refresh tokens
+    JWT_REFRESH_COOKIE_NAME="refresh_token_cookie",
+    JWT_REFRESH_COOKIE_PATH="/",
+    JWT_COOKIE_SECURE=False,  # Set to True in production (requires HTTPS)
+    JWT_COOKIE_HTTP_ONLY=True,  # Prevent JavaScript access to refresh token
+    JWT_COOKIE_SAMESITE="lax",  # Protect against CSRF
+    JWT_COOKIE_CSRF_PROTECT=True,  # Enable CSRF protection for cookie-based refresh
+    JWT_REFRESH_CSRF_COOKIE_NAME="csrf_refresh_token",
+    JWT_REFRESH_CSRF_HEADER_NAME="X-CSRF-TOKEN",
+)
+
+# Initialize AuthX
+auth = AuthX(config=auth_config)
+
+# Register error handlers
+auth.handle_errors(app)
+
+
+# Define models
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+# Sample user database (in a real app, you would use a database)
+USERS = {
+    "user1": {"password": "password1", "email": "[email protected]"},
+    "user2": {"password": "password2", "email": "[email protected]"},
+}
+
+
+@app.post("/login", response_model=TokenResponse)
+def login(data: LoginRequest, response: Response):
+    """Login endpoint that:
+    - Returns access_token in the response body (for client to store in memory)
+    - Sets refresh_token as an HTTP-only cookie (for secure storage).
+    """
+    # Validate credentials
+    if data.username not in USERS or USERS[data.username]["password"] != data.password:
+        raise HTTPException(status_code=401, detail="Invalid username or password")
+
+    # Create tokens
+    access_token = auth.create_access_token(uid=data.username)
+    refresh_token = auth.create_refresh_token(uid=data.username)
+
+    # Set ONLY the refresh token in a cookie (with CSRF protection)
+    # The access token is NOT stored in a cookie - it will be in client memory
+    auth.set_refresh_cookies(refresh_token, response)
+
+    # Return access token in response body
+    # Client should store this in memory (not localStorage for XSS protection)
+    return TokenResponse(access_token=access_token)
+
+
+@app.post("/refresh", response_model=TokenResponse)
+async def refresh(request: Request):
+    """Refresh endpoint that:
+    - Reads refresh_token from the HTTP-only cookie (automatically sent by browser)
+    - Validates the refresh token
+    - Returns a new access_token in the response body.
+
+    For POST requests with cookies, CSRF token must be included in X-CSRF-TOKEN header.
+    """
+    try:
+        # Get refresh token from COOKIES only (not headers)
+        # The locations parameter restricts where to look for the token
+        refresh_token = await auth.get_refresh_token_from_request(
+            request,
+            locations=["cookies"],  # Only look in cookies
+        )
+
+        # Verify the refresh token (CSRF is verified automatically for cookies)
+        payload = auth.verify_token(refresh_token, verify_type=True)
+
+        # Create a new access token
+        new_access_token = auth.create_access_token(uid=payload.sub)
+
+        # Return in response body (client stores in memory)
+        return TokenResponse(access_token=new_access_token)
+
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=str(e)) from e
+
+
+@app.get("/protected")
+async def protected_route(request: Request):
+    """Protected route that requires access_token in the Authorization header.
+
+    Example request:
+        curl -H "Authorization: Bearer <access_token>" http://localhost:8000/protected
+    """
+    try:
+        # Get access token from HEADERS only (not cookies)
+        access_token = await auth.get_access_token_from_request(
+            request,
+            locations=["headers"],  # Only look in headers
+        )
+
+        # Verify the access token
+        # No CSRF verification needed for header-based tokens
+        payload = auth.verify_token(access_token, verify_csrf=False)
+
+        # Get user info
+        username = payload.sub
+        user_data = USERS.get(username, {})
+
+        return {
+            "message": "Access granted",
+            "username": username,
+            "email": user_data.get("email"),
+            "token_location": access_token.location,
+        }
+
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=str(e)) from e
+
+
+@app.post("/protected-action")
+async def protected_action(request: Request):
+    """Protected POST route that requires access_token in the Authorization header.
+
+    This demonstrates that even for POST requests, when using header-based auth,
+    no CSRF token is needed (CSRF is only a concern for cookie-based auth).
+    """
+    try:
+        # Get access token from HEADERS only
+        access_token = await auth.get_access_token_from_request(
+            request,
+            locations=["headers"],
+        )
+
+        # Verify the access token (no CSRF for headers)
+        payload = auth.verify_token(access_token, verify_csrf=False)
+
+        return {
+            "message": "Action performed successfully",
+            "username": payload.sub,
+        }
+
+    except Exception as e:
+        raise HTTPException(status_code=401, detail=str(e)) from e
+
+
+@app.post("/logout")
+def logout(response: Response):
+    """Logout endpoint that clears the refresh token cookie.
+
+    The access token (stored in client memory) will naturally be cleared
+    when the client discards it or the page is refreshed.
+    """
+    # Only unset refresh cookies (access token is in client memory, not managed by server)
+    auth.unset_refresh_cookies(response)
+    return {"message": "Successfully logged out"}
+
+
+@app.get("/")
+def read_root():
+    """Public route with API documentation."""
+    return {
+        "message": "AuthX Dual Token Location Example",
+        "description": "Access tokens in headers, refresh tokens in cookies",
+        "flow": {
+            "1_login": "POST /login - Returns access_token in body, sets refresh_token cookie",
+            "2_api_call": "GET /protected - Send access_token in Authorization header",
+            "3_refresh": "POST /refresh - Refresh token sent via cookie, returns new access_token",
+            "4_logout": "POST /logout - Clears refresh_token cookie",
+        },
+        "example_requests": {
+            "login": 'curl -X POST -H "Content-Type: application/json" -d \'{"username":"user1","password":"password1"}\' http://localhost:8000/login',
+            "protected": 'curl -H "Authorization: Bearer <access_token>" http://localhost:8000/protected',
+            "refresh": 'curl -X POST -b "refresh_token_cookie=<token>" -H "X-CSRF-TOKEN: <csrf_token>" http://localhost:8000/refresh',
+            "logout": "curl -X POST http://localhost:8000/logout",
+        },
+    }
+
+
+if __name__ == "__main__":
+    import os
+
+    import uvicorn
+
+    port = int(os.environ.get("PORT", 8000))
+    uvicorn.run(app, host="0.0.0.0", port=port)