Auth Page Customization
Tenant-controlled branding image displayed on the login, register, and other auth pages
Auth Page Customization
Each tenant can upload a custom auth page image that appears on every authentication screen — login, register, forgot password, reset password, verify email, verify phone, and complete profile. It's a simple but effective branding lever: same product, your imagery.
Where it Appears
The image fills the right-hand panel of the auth form layout on medium-and-larger viewports. On mobile (< md), the image panel is hidden so the form takes the full width.
Affected pages (anything wrapped in AuthFormLayout):
| Page | Path |
|---|---|
| Login | /auth/login |
| Register | /auth/register |
| Forgot Password | /auth/forgot-password |
| Reset Password | /auth/reset-password |
| Verify Email | /auth/verify-email |
| Verify Phone | /auth/verify-phone |
| Complete Profile | /auth/complete-profile |
If no image is configured, the layout falls back to /placeholder.svg.
Configuring the Image (Admin)
- Sign in as an admin with platform settings permission.
- Go to Admin → Settings → Media.
- Find the Auth Page Image field.
- Upload an image (any
image/*type). - Save.
The change takes effect on the next page load — there is no per-user cache.
Image Recommendations
- The image is rendered with
object-coverinside a tall, narrow panel — pick artwork that crops well vertically and doesn't depend on visible edges. - In dark mode the image is auto-dimmed (
brightness-[0.2] grayscale) so detail is muted intentionally — use a high-contrast image if you want shapes still readable in the dark. - Aim for landscape-to-portrait ratios in the 3:4 to 1:1 range to look good across breakpoints.
- Use a CDN-friendly format (WebP or optimized JPEG) — the image is loaded via
next/imagewithfilland responsivesizesfor performance.
Where it Lives in the Stack
- Setting field:
media.auth_page_image(string URL, optional) - Backend type:
MediaSettings.AuthPageImage *stringincommon/pkg/tenant/settings.go - Public read endpoint:
GET /v1/public/tenant/settings(no auth required — needed because the auth pages themselves are unauthenticated) - Frontend consumer:
src/components/auth/auth-form-layout.tsx, via theusePublicTenantSettings()hook - Admin UI definition:
src/lib/settings/config.ts(Media section, field idauth_page_image)
Multi-Tenancy
The image is per-tenant. Each tenant's auth pages render that tenant's configured image, resolved from the same public tenant settings endpoint that drives the login form's password policy and tenant name.
Troubleshooting
| Issue | Solution |
|---|---|
| Image not appearing after upload | Hard-refresh the auth page; verify the upload succeeded in Admin → Settings → Media and that a non-empty URL is saved |
| Image looks washed out in dark mode | This is by design — the layout applies brightness-[0.2] grayscale in dark mode. Pick a higher-contrast image or accept the subdued look |
| Image only shows on desktop | Correct — the image panel is hidden on mobile (< md breakpoint) so the form has full width |
| Old image still showing | The browser/CDN may have cached it. Re-upload with a different filename or wait for cache expiry |
| Want different images per page | Not supported today — there is one auth_page_image per tenant covering all auth pages |