orion/docs/development/auth-dependencies-guide.md

Authentication Dependencies Guide

Overview

FastAPI routes use different authentication dependencies based on whether they serve HTML pages or API endpoints.

Available Dependencies

Admin Authentication

Dependency	Use Case	Accepts	Description
get_current_admin_from_cookie_or_header	HTML pages	Cookie OR Header	For admin HTML routes like /admin/dashboard
get_current_admin_api	API endpoints	Header ONLY	For admin API routes like /api/v1/admin/stores
get_current_admin_optional	Login pages	Cookie OR Header	Returns None instead of raising exception

Store Authentication

Dependency	Use Case	Accepts	Description
get_current_store_from_cookie_or_header	HTML pages	Cookie OR Header	For store HTML routes like /store/{code}/dashboard
get_current_store_api	API endpoints	Header ONLY	For store API routes like /api/v1/store/{code}/products
get_current_store_optional	Login pages	Cookie OR Header	Returns None instead of raising exception

Customer Authentication

Dependency	Use Case	Accepts	Description
get_current_customer_from_cookie_or_header	HTML pages	Cookie OR Header	For storefront account pages like /storefront/account/dashboard
get_current_customer_api	API endpoints	Header ONLY	For storefront API routes like /api/v1/storefront/cart
get_current_customer_optional	Login pages	Cookie OR Header	Returns None instead of raising exception

When to Use Which?

Use _from_cookie_or_header for HTML Pages

HTML pages that render templates and are accessed by browsers:

# app/routes/admin_pages.py
from app.api.deps import get_current_admin_from_cookie_or_header

@router.get("/admin/dashboard", response_class=HTMLResponse)
async def admin_dashboard(
    request: Request,
    current_user: User = Depends(get_current_admin_from_cookie_or_header)
):
    return templates.TemplateResponse("admin/dashboard.html", {...})

Why? Browsers automatically send cookies, making this seamless for page navigation.

Use _api for API Endpoints

JSON API endpoints that are called by JavaScript:

# app/api/v1/admin/stores.py
from app.api.deps import get_current_admin_api

@router.get("/api/v1/admin/stores")
async def list_stores(
    current_user: User = Depends(get_current_admin_api),
    db: Session = Depends(get_db)
):
    return {"stores": [...]}

Why?

• Security: API endpoints should NOT accept cookies (prevents CSRF attacks)
• Explicit: JavaScript must explicitly set Authorization header
• Stateless: API calls are stateless and don't rely on browser cookies

Use _optional for Login Pages

Login pages that redirect if already authenticated:

# app/routes/admin_pages.py
from app.api.deps import get_current_admin_optional

@router.get("/admin/login", response_class=HTMLResponse)
async def admin_login_page(
    request: Request,
    current_user: Optional[User] = Depends(get_current_admin_optional)
):
    if current_user:
        return RedirectResponse("/admin/dashboard")
    return templates.TemplateResponse("admin/login.html", {...})

Why? Avoids showing login page to already-authenticated users.

Migration Guide

Old vs New Names

The authentication dependencies were renamed for clarity:

❌ Old Name (REMOVED)	✅ New Name	Type
get_current_admin_user	get_current_admin_from_cookie_or_header	HTML pages
get_current_admin_user	get_current_admin_api	API endpoints
get_current_store_user	get_current_store_from_cookie_or_header	HTML pages
get_current_store_user	get_current_store_api	API endpoints

How to Update Your Code

1. Identify route type: Is it an HTML page or API endpoint?
2. Choose correct dependency:
   • HTML page → _from_cookie_or_header
   • API endpoint → _api
3. Update import and usage

Example 1: HTML Page Route

Before:

from app.api.deps import get_current_admin_user  # ❌ Doesn't exist

@router.get("/admin/settings")
def settings_page(current_user: User = Depends(get_current_admin_user)):
    ...

After:

from app.api.deps import get_current_admin_from_cookie_or_header  # ✅

@router.get("/admin/settings")
def settings_page(
    current_user: User = Depends(get_current_admin_from_cookie_or_header)
):
    ...

Example 2: API Endpoint

Before:

from app.api.deps import get_current_admin_user  # ❌ Doesn't exist

@router.post("/api/v1/admin/stores")
def create_store(current_user: User = Depends(get_current_admin_user)):
    ...

After:

from app.api.deps import get_current_admin_api  # ✅

@router.post("/api/v1/admin/stores")
def create_store(current_user: User = Depends(get_current_admin_api)):
    ...

Quick Reference

# All available in app.api.deps

# ADMIN
from app.api.deps import (
    get_current_admin_from_cookie_or_header,  # HTML pages
    get_current_admin_api,                     # API endpoints
    get_current_admin_optional,                # Login pages
)

# STORE
from app.api.deps import (
    get_current_store_from_cookie_or_header,  # HTML pages
    get_current_store_api,                     # API endpoints
    get_current_store_optional,                # Login pages
)

# CUSTOMER
from app.api.deps import (
    get_current_customer_from_cookie_or_header,  # HTML pages
    get_current_customer_api,                     # API endpoints
    get_current_customer_optional,                # Login pages
)

# GENERIC (any authenticated user)
from app.api.deps import get_current_user  # Header-only, any role

See Also

• Authentication Documentation - Complete auth system docs
• Authentication Flow Diagrams - Visual flows
• Source code: app/api/deps.py - Authentication dependency implementations