Assets & Backgrounds

Themes support three hosted asset kinds: a logo (theme app icon), a background image, and provider icons (one optional icon per identity provider). Assets are uploaded directly from the theme editor, stored in BluAuth's S3 bucket, and served from BluAuth's CDN — there's no external CDN to configure and no sidecar hosting to manage.

Logo (app icon)

The logo is the single most-used asset. It shows in more places than any other theme field.

Where the logo appears:

• The hero panel of split-hero and cinematic-split layouts.
• The top of the form card on centered-card and aurora layouts.
• Above the heading on minimal (small).
• The header of every email sent by BluAuth — invitation, password reset, welcome, account-linking prompts.
• The meta tile (<meta property="og:image">) served alongside the hosted login page.

Recommended specs:

Why SVG first: SVG scales cleanly across every surface (the 256px hero logo, the 48px form-card logo, the 32px email header, the 16px favicon) without raster artifacts. PNGs work but require a ~512px source to avoid blurry edges on retina.

Leave the Logo field empty to fall back to the default BluAuth shield icon.

Background image

An optional image that replaces the default gradient canvas.

Modes

The Background Image Mode field (backgroundImageMode) controls how the image positions:

• Framed — the image renders inside a rounded rectangle centered behind the form, with a subtle inset ring. Best for photography you want to frame, not fill. The image does not reach the viewport edges; the theme's background color shows around the frame.
• Full Bleed — the image covers the full viewport edge-to-edge. Best for immersive brand imagery and consumer-facing launches.

Specs

Where the background image does not render

• Minimal layout — the minimal layout is designed to be chromeless. It never renders a background image, even if one is set.
• Aurora layout — aurora is the background. Background images are ignored.
• Emails — the background image never ships in email. Email clients strip most imagery, and those that don't would render a misaligned image behind your form-less email body.
• cinematic-split form side — the background fills the hero column only, not the form panel.

Provider icons

Each identity provider (Google, Microsoft, Okta, custom OIDC, SAML) can optionally carry a custom icon. If not set, BluAuth uses a sensible default from i-lucide-* — a generic shield for SAML, a key-round for OIDC, the Chrome icon for Google, etc.

To upload a provider icon, open the provider detail page under /admin/providers/:id and use the Icon upload in the identity display panel. Icon assets have the same 512 KB / SVG-preferred constraints as logos.

Custom icons are most useful for:

• Generic OIDC providers where the default key-round icon is uninformative (e.g. a provider that's actually Okta dressed as OIDC — upload the Okta mark).
• Branded SAML providers where the generic file-lock icon looks too lo-fi for a consumer app.
• Internal tenants who have strict brand guidelines — upload your own mark so the button doesn't look generic.

See the providers guide for how provider styling flows into the hosted login.

The asset pipeline

Upload flow

1. You select a file in the studio (drag-drop or click the upload tile).
2. The client requests a presigned URL from /api/admin/assets/presign — this step includes a content-type check and size validation against the asset kind's limit.
3. The client uploads directly to S3 via the presigned URL. The file never travels through the Nuxt server.
4. On success, BluAuth writes an assetObjects row with the S3 key, content-type, and size.
5. The studio field updates to the CDN-backed public URL.

KMS encryption

Assets are stored with server-side encryption via AWS KMS (SSE-KMS) using BluAuth's tenant asset key. The encryption is transparent — reads go through the CDN and decrypt at fetch time. You don't need to configure anything; the pipeline handles it.

In local development without AWS credentials, asset uploads route to a local MinIO bucket with SSE disabled — functional for local dev, not production-like for testing encryption paths.

Caching

• Uploaded assets get a 1-year Cache-Control header and an immutable hash in their URL. Once an asset is uploaded, its URL never changes content.
• Replacing an asset uploads a new URL — the old one is not automatically cleaned up. This is intentional: if you rebind a theme and want to roll back, the old URL still resolves.
• The hosted login page caches the resolved theme (including asset URLs) in Valkey for 60 seconds per client. Expect new asset uploads to show on production within a minute.
• Long cache TTLs combine with hash-busted URLs to give you the performance of a CDN without the invalidation pain.

Internal hosting vs external CDN

BluAuth hosts everything on its own S3 + CloudFront pair — you do not need to provide an external CDN. If you need to reference an external asset (e.g. a marketing team's CMS-hosted hero), set the URL field directly in the clientThemes row via the admin API. Note that external URLs bypass our cache and encryption pipeline; upload a copy to BluAuth when you can.

Replacing assets

Upload a new file. The field updates to the new URL. The old asset stays in S3 for auditability; manual cleanup is available via the /admin/assets management view if a tenant needs hard-delete for compliance.

Accessibility

• Logo alt text — BluAuth uses alt="Logo" as the default. Per-tenant alt text overrides are not currently in the UI; if you need this, file an issue.
• Background images — rendered with aria-hidden="true" since they're decorative. If your image contains meaningful content (text, a product), that content must also be available in copy — don't rely on the image alone.
• Provider icons — fall back to the provider name in an aria-label when no icon is set.

Size limits — at a glance

Uploads over the limit fail at the presign step with a 413 — the studio surfaces the error inline at the upload tile.

Next

• Layouts — how each layout uses (or doesn't use) the background image.
• Styling tokens — how surface color interacts with full-bleed backgrounds.
• Providers guide — upload and manage per-provider icons.