Getting Started

This guide will help you get started with DRF Auth Kit quickly and easily.

Quick Setup

Basic Django Configuration

Add the required apps to INSTALLED_APPS and configure authentication:

# settings.py
INSTALLED_APPS = [
    # ... your existing apps
    'rest_framework',
    'allauth',             # Required
    'allauth.account',     # Required
    'auth_kit',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'auth_kit.authentication.JWTCookieAuthentication',
    ],
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

# AUTH_KIT uses sensible defaults (AUTH_TYPE='jwt', USE_AUTH_COOKIE=True)
# Override only if needed

Include URLs and run migrations:

# urls.py
urlpatterns = [
    path('api/auth/', include('auth_kit.urls')),
    # Your other URLs
]

# Terminal
python manage.py migrate

For detailed configuration options, see Configuration.

Multi-Factor Authentication (MFA) Setup

Enable MFA: Add MFA support to your application:

# Add MFA to INSTALLED_APPS
INSTALLED_APPS = [
    # ... your existing apps
    'auth_kit',
    'auth_kit.mfa',  # MFA functionality
]

# Enable MFA in AUTH_KIT settings
AUTH_KIT = {
    'USE_MFA': True,  # Enables MFA authentication flow
}

# Run migrations for MFA models
# python manage.py migrate

MFA Authentication Flow: When MFA is enabled, the login process becomes two-step:

  1. Step 1: POST /api/auth/login/ - Username/password authentication

  2. Step 2: POST /api/auth/login/verify/ - MFA code verification

Available MFA Methods:

  • Email MFA: Sends TOTP codes via email (requires email configuration)

  • Authenticator App: Generates QR codes for Google Authenticator, Authy, etc.

  • Backup Codes: Automatic generation of recovery codes

Additional Endpoints: When MFA is enabled, these endpoints become available:

  • GET|POST /api/auth/mfa/ - MFA method management

  • POST /api/auth/login/change-method/ - Change MFA method during login

  • POST /api/auth/login/resend/ - Resend MFA code

Social Authentication Setup

Automatic URL Generation: When you include auth_kit.social.urls, the system automatically generates authentication URLs for any installed Django Allauth social providers. No need to manually define URLs for each provider.

Provider Configuration: Add social providers to INSTALLED_APPS and configure them in SOCIALACCOUNT_PROVIDERS:

# Add social providers to INSTALLED_APPS
INSTALLED_APPS = [
    # ... your existing apps
    'allauth.socialaccount',
    'allauth.socialaccount.providers.google',  # Google OAuth2
    'allauth.socialaccount.providers.github',  # GitHub OAuth2
    'auth_kit.social',  # DRF Auth Kit social integration
]

# Configure social providers
SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': ['profile', 'email'],
        'AUTH_PARAMS': {'access_type': 'online'},
        'OAUTH_PKCE_ENABLED': True,
        'APP': {
            'client_id': 'your-google-client-id',
            'secret': 'your-google-client-secret',
        }
    },
}

# Include social URLs
urlpatterns = [
    path('api/auth/', include('auth_kit.urls')),
    path('api/auth/social/', include('auth_kit.social.urls')),
]

API Documentation Setup

DRF Auth Kit includes automatic OpenAPI schema generation. Set up DRF Spectacular to explore the API:

# settings.py
INSTALLED_APPS = [
    # ... your existing apps
    'drf_spectacular',
]

SPECTACULAR_SETTINGS = {
    'TITLE': 'Your API Documentation',
    'DESCRIPTION': 'API documentation with authentication',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

# urls.py
from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
    SpectacularRedocView,
)

urlpatterns = [
    # ... your existing URLs
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

Visit /api/docs/ to explore the complete API documentation with all available authentication endpoints.

UI Testing View (Development Only)

DRF Auth Kit provides a comprehensive UI view for testing all authentication features in development:

# urls.py
from auth_kit.views import AuthKitUIView
from django.conf import settings

urlpatterns = [
    # ... your existing URLs
    path('api/auth/', include('auth_kit.urls')),
]

# Include UI testing view only in DEBUG mode
if settings.DEBUG:
    urlpatterns += [
        path('api/auth/ui/', AuthKitUIView.as_view(), name='auth_kit_ui'),
    ]

Features:

  • Interactive forms for registration, login, and logout

  • User profile management interface

  • Password change and reset functionality

  • Social authentication testing (if configured)

  • MFA enrollment and verification (if enabled)

  • Real-time API response viewer

  • All auth features in one convenient page

Visit /api/auth/ui/ (in development) to access the testing interface.

Important: This UI view is designed for development and testing purposes only. Use the DEBUG conditional to ensure it’s not exposed in production.

External Library Configuration

For advanced configuration, refer to the official documentation:

Next Steps