Skip to Content
FeaturesBundled ExtensionsUser ManagementAccountsFrontend Integration

Frontend Integration

Two packages cover the full frontend auth stack:

PackageWhat it provides
@djangocfg/apiType-safe API client, hooks, JWT management, server middleware
@djangocfg/layoutsAuthLayout — drop-in multi-step auth UI

AuthLayout

The fastest path — a complete authentication UI from @djangocfg/layouts. One component, all steps handled.

// app/auth/page.tsx
import { AuthLayout } from '@djangocfg/layouts'
 
export default function LoginPage() {
  return (
    <AuthLayout
      redirectUrl="/dashboard"
      enableGithubAuth={true}
      termsUrl="/terms"
      privacyUrl="/privacy"
    />
  )
}

Auth steps

identifier  →  otp  →  [2fa]  →  [2fa-setup]  →  success → redirect

2fa and 2fa-setup steps appear automatically if 2FA is enabled for the user.

Props

PropTypeDefaultDescription
redirectUrlstring/dashboardWhere to go after success
sourceUrlstring—App URL for analytics / OTP emails
enableGithubAuthbooleanfalseShow GitHub OAuth button
enablePhoneAuthbooleanfalseAllow phone number input
enable2FASetupbooleantruePrompt 2FA setup after first login
logoUrlstring—Logo on the success screen
termsUrlstring—Terms of service link
privacyUrlstring—Privacy policy link
supportUrlstring—Support page link
childrenReactNode—Custom header — rendered on identifier step only

Callbacks

<AuthLayout
  onIdentifierSuccess={(identifier) => console.log('OTP sent to', identifier)}
  onOTPSuccess={() => console.log('verified')}
  onOAuthSuccess={(user, isNewUser, provider) => console.log(provider, user)}
  onError={(message) => console.error(message)}
/>

Accessing step state from child components

import { useAuthFormContext } from '@djangocfg/layouts'
 
const { step, identifier, isLoading } = useAuthFormContext()

AuthProvider

AuthProvider from @djangocfg/api/auth manages tokens, user state, and auto-refresh. Required for all auth hooks.

When using @djangocfg/layouts, AuthProvider is already included inside AppLayout / BaseApp — no manual setup needed.

For standalone usage:

// app/layout.tsx
import { AuthProvider } from '@djangocfg/api/auth'
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider config={{ routes: { auth: '/auth', defaultCallback: '/dashboard' } }}>
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}

Auth Hooks

useAuth — user state and OTP methods

'use client'
import { useAuth } from '@djangocfg/api/auth'
 
const { user, isAuthenticated, isLoading, requestOTP, verifyOTP, logout } = useAuth()
ValueTypeDescription
userUserProfile | nullCurrent user
isAuthenticatedboolean—
isLoadingbooleanInitial auth check in progress
requestOTPfnSend OTP to email
verifyOTPfnVerify code → stores JWT
logoutfnClears tokens

useAuthGuard — route protection

'use client'
import { useAuthGuard } from '@djangocfg/api/auth'
 
const { isAllowed } = useAuthGuard({ redirectTo: '/auth', requireAuth: true })
if (!isAllowed) return null

useAuthForm — multi-step form state

'use client'
import { useAuthForm } from '@djangocfg/api/auth'
 
const {
  step,                      // 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success'
  identifier, setIdentifier,
  otp, setOtp,
  isLoading, error,
  isRateLimited, rateLimitLabel,   // countdown string e.g. "1:30"
  handleIdentifierSubmit,
  handleOTPSubmit,
  handleResendOTP,
  handleBackToIdentifier,
} = useAuthForm({
  sourceUrl: window.location.origin,
  redirectUrl: '/dashboard',
  requireTermsAcceptance: false,
  onIdentifierSuccess: (id) => {},
  onOTPSuccess: () => {},
  onError: (msg) => {},
})

useGithubAuth — OAuth

'use client'
import { useGithubAuth } from '@djangocfg/api/auth'
 
const { startGithubAuth, isLoading, error } = useGithubAuth({
  sourceUrl: window.location.origin,
})
// startGithubAuth() → redirects to GitHub

OAuth callback is handled automatically by AuthLayout.

useTwoFactor — verify TOTP during login

'use client'
import { useTwoFactor } from '@djangocfg/api/auth'
 
const { verify, isLoading, error } = useTwoFactor({
  sessionId,
  onSuccess: (user) => {},
  redirectUrl: '/dashboard',
})

useTwoFactorSetup — enable/disable 2FA for authenticated users

'use client'
import { useTwoFactorSetup } from '@djangocfg/api/auth'
 
const { qrCode, secret, isEnabled, startSetup, verifySetup, disable } = useTwoFactorSetup({
  onSetupComplete: () => {},
  onDisabled: () => {},
})

useTwoFactorStatus — check and manage 2FA status

'use client'
import { useTwoFactorStatus } from '@djangocfg/api/auth'
 
const { has2FAEnabled, devices, fetchStatus, disable2FA } = useTwoFactorStatus()

Server Components & SWR Hooks

Server component (fetcher)

import { Fetchers, api } from '@djangocfg/api'
 
export default async function ProfilePage() {
  const profile = await Fetchers.getAccountsProfileRetrieve(api)
  return <div>{profile.email}</div>
}

Client hook (SWR)

'use client'
import { useAccountsProfileRetrieve } from '@djangocfg/api/hooks'
 
const { data: profile, isLoading, mutate } = useAccountsProfileRetrieve()

Server Middleware

Proxies /media/* and /api/* to the Django backend, forwarding cookies and auth headers automatically:

// middleware.ts
import { proxyMiddleware } from '@djangocfg/api/auth/server'
import { NextRequest } from 'next/server'
 
export function middleware(request: NextRequest) {
  return proxyMiddleware(request)
}
 
export const config = {
  matcher: ['/media/:path*', '/api/:path*'],
}

Analytics Events

Auth events are tracked automatically when analytics is configured in AppLayout:

EventTrigger
AUTH_LOGIN_SUCCESSOTP verify or OAuth success
AUTH_LOGOUTlogout() called
AUTH_OAUTH_START / _SUCCESS / _FAILGitHub OAuth flow
AUTH_2FA_SETUP_COMPLETE2FA enabled
AUTH_2FA_VERIFY_SUCCESS / _FAIL2FA code verification

Environment Variables

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GITHUB_CLIENT_ID=Iv1.abc123  # OAuth only

See Also

TAGS: accounts, frontend, AuthLayout, useAuth, useAuthForm, @djangocfg/api, @djangocfg/layouts DEPENDS_ON: [accounts/index]

Last updated on
OverviewOTP & Brute-Force Protection

Django-CFG documentation — a modern, type-safe Django framework with Pydantic v2 configuration.

Documentation

Frontend

Resources

Company

© 2026 Django-CFG. MIT Licensed.GitHub ↗