📣 Wristband FastAPI Auth SDK 2.0.0 Release 🎉

Release v2.0.0

Breaking Changes

Migration Guide: https://github.com/wristband-dev/fastapi-auth/blob/main/migration/v2/README.md

🔄 CallbackResult Structure Changes

The CallbackResult model now uses a discriminated union pattern with explicit variant types.

Migration:

• Use isinstance() checks instead of comparing callback_result.type
• Import new result types: CompletedCallbackResult, RedirectRequiredCallbackResult
• No more assert statements needed - type narrowing is automatic
• New reason field added to RedirectRequiredCallbackResult

📝 Query Parameter and URL Placeholder Standardization

Query Parameters:

• tenant_domain → tenant_name

URL Placeholders:

• {tenant_domain} → {tenant_name} ({tenant_domain} is deprecated but still supported for backward compatibility and will be removed in future versions)

🔧 Session Middleware Configuration Changes

SameSite Parameter:

• String literal ("lax") → Enum value (SameSiteOption.LAX)
• Must import SameSiteOption from wristband.fastapi_auth

CSRF Configuration:

• enable_csrf_protection is now opt-in (default: False)
• In v1.x, CSRF tokens were always generated
• Must explicitly enable CSRF protection if needed

🛡️ Session Auth Dependency Changes

Method Signature:

• New enable_csrf_protection parameter added (default: False)
• Must explicitly enable CSRF protection if needed

New Features

🔐 JWT Authentication Dependency

New create_jwt_auth_dependency() supports WT bearer token authentication powered by @wristband/python-jwt.

Features:

• Stateless JWT validation with JWKS
• Configurable JWK cache size and TTL
• Decoded JWT payload available in JWTAuthResult
• Full type safety with Pydantic models

✨ Multi-Strategy Authentication Dependency

New create_auth_dependency() supports multiple authentication strategies with fallback behavior.

Supported Strategies:

• SESSION - Cookie-based session authentication with automatic token refresh
• JWT - Bearer token authentication with JWKS validation

Features:

• Try multiple strategies in order until one succeeds
• Automatic access token refresh for expired tokens (SESSION strategy)
• Optional CSRF token validation (SESSION strategy)
• Rolling session windows (SESSION strategy)
• Configurable JWKS caching (JWT strategy)

🔄 Callback Failure Reasons

CallbackResult now includes a reason field when isinstance(callback_result, RedirectRequiredCallbackResult):

• MISSING_LOGIN_STATE - Login state cookie not found
• INVALID_LOGIN_STATE - Login state validation failed
• LOGIN_REQUIRED - Wristband returned login_required error
• INVALID_GRANT - Authorization code was invalid or expired

📦 Enhanced Session Management

New Features:

• Explicit CSRF protection configuration at both middleware and dependency levels
• SameSiteOption enum for type-safe cookie settings
• Enhanced session configuration with separate CSRF cookie domain support

Recommended Updates

📋 Session and Token Endpoint Headers

Add no-cache headers to session and token endpoints to prevent caching:

response.headers["Cache-Control"] = "no-store"
response.headers["Pragma"] = "no-cache"

For full documentation, see the README.