Getting started¶

1. Install¶

uv add bluefox-auth

2. Set up your app¶

from bluefox_core.app import create_bluefox_app
from bluefox_core.settings import BluefoxSettings
from bluefox_auth import BluefoxAuth

settings = BluefoxSettings()
app = create_bluefox_app(settings)
BluefoxAuth(app, settings)

BluefoxAuth reads SECRET_KEY from your settings object, builds internal AuthSettings, mounts the auth router, and stores everything on app.state.

SECRET_KEY is required

Your settings must have a SECRET_KEY attribute with at least 32 characters. The app will crash on startup if it's missing, too short, or set to a placeholder like "change-me-in-production".

Generate one:

python -c "import secrets; print(secrets.token_urlsafe(64))"

3. Run migrations¶

bluefox-auth defines two tables (users and refresh_tokens) via SQLAlchemy models that extend BluefoxBase. Run your Alembic migrations to create them:

alembic revision --autogenerate -m "add auth tables"
alembic upgrade head

4. Protect routes¶

from fastapi import Depends
from bluefox_auth import current_active_user, BluefoxUser

@app.get("/dashboard")
async def dashboard(user: BluefoxUser = Depends(current_active_user)):
    return {"message": f"Hello, {user.email}"}

For admin-only routes:

from bluefox_auth import current_superuser

@app.delete("/admin/users/{user_id}")
async def delete_user(user_id: int, admin: BluefoxUser = Depends(current_superuser)):
    ...

5. Choose your transport¶

bluefox-auth supports two token transports, auto-detected per request:

Bearer header — for API clients, mobile apps, SPAs that manage tokens in memory
HttpOnly cookies — for browser apps with CSRF protection built in

Both are always active. The login endpoint returns tokens in the JSON body and sets cookies simultaneously. See the API auth and Cookie auth guides for details.

Configuration options¶

BluefoxAuth(
    app,
    settings,
    prefix="/api/auth",              # Custom route prefix (default: "/auth")
    user_model=MyUser,               # Custom user model (default: BluefoxUser)
    cookie_secure=False,             # Disable Secure flag for local dev
    cookie_domain=".example.com",    # Set cookie domain
    password_reset_send_fn=send_pw,  # Enable password reset
    email_verify_send_fn=send_ev,    # Enable email verification
)

See BluefoxAuth setup for full details.