Storage Adapter (Branding Uploads)
The optional storage adapter lets admins upload branding files (logo, favicon, powered-by logo, background image and font) instead of pasting URLs. An upload returns a URL that goes into the existing branding URL field, so the branding schema is unchanged and external URLs keep working.
Without a storage adapter, the upload endpoint returns 501 and the admin UI behaves as before.
Interface
interface StorageAdapter {
put(
key: string,
body: ArrayBuffer | Uint8Array,
options: { contentType: string; cacheControl?: string },
): Promise<void>;
get(key: string): Promise<{
body: ReadableStream<Uint8Array>;
contentType?: string;
cacheControl?: string;
size?: number;
etag?: string;
} | null>;
delete(key: string): Promise<void>;
// Public URL when files are served from a dedicated assets domain, otherwise undefined.
getPublicUrl(key: string): string | undefined | Promise<string | undefined>;
}Set it as data.storage. If you configure managementDataAdapter, set storage on that object too (uploads and /assets read from it). Uploads and /assets must resolve the same store, so per-tenant isolated adapters must share one branding bucket. To support S3 or local disk, implement these four methods; nothing in authhero needs to change.
Cloudflare R2
All tenants share one bucket. This is a one-time setup per environment, nothing is provisioned per tenant.
Create the bucket:
wrangler r2 bucket create authhero-assetsBind it in
wrangler.toml:toml[[r2_buckets]] binding = "ASSETS" bucket_name = "authhero-assets"Pass it to the Cloudflare adapter and use the resulting
storagein your data adapter:tsconst cloudflare = createAdapters({ // ...existing config storage: { bucket: env.ASSETS }, }); const dataAdapter = { ...baseAdapters, storage: cloudflare.storage };
How files are served
By default the auth server serves files itself at /assets/tenants/{tenant_id}/branding/{kind}/{file}. The route is public and sets immutable cache headers, Access-Control-Allow-Origin: * (fonts are loaded cross-origin), nosniff and a restrictive Content-Security-Policy. The bucket can stay private and no extra configuration is needed.
To serve from one shared assets domain instead, attach a custom domain to the bucket and set publicBaseUrl:
storage: { bucket: env.ASSETS, publicBaseUrl: "https://assets.example.com" }publicBaseUrlonly changes the URL returned by the upload API;/assetsstays mounted.- Fonts need an R2 CORS policy allowing
GETfrom your login origins. If you can't set one, omitpublicBaseUrl. - SVG files always use the
/assetsURL so the restrictive CSP applies to the URL the API returns, not to direct bucket access. They are still stored in the bucket, so they are also reachable atpublicBaseUrl/<key>without that CSP. Add a Cloudflare Transform Rule on the assets domain that setsContent-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox(andX-Content-Type-Options: nosniff) for.svgpaths, or don't expose the bucket publicly.
Stored URLs are plain URLs, so you can later point per-tenant subdomains at the tenants/{tenant_id}/ prefix, or move a tenant to its own bucket, by copying objects and updating the URL.
Keys and lifecycle
Objects are stored as tenants/{tenant_id}/branding/{kind}/{uuid}.{ext}, where kind is logo, favicon, powered_by_logo, background or font. The tenant id comes from the authenticated request. Every upload gets a new random name, so URLs are immutable and cacheable for a year. Replacing a file does not delete the previous object.
Limits
| Kind | Types | Max size |
|---|---|---|
logo, powered_by_logo | PNG, JPEG, WebP, GIF, SVG | 2 MB |
favicon | PNG, JPEG, WebP, GIF, SVG, ICO | 512 KB |
background | PNG, JPEG, WebP, SVG | 5 MB |
font | WOFF2, WOFF, TTF, OTF | 2 MB |
The file's bytes must match its resolved type. The type is the declared one, except for fonts: an empty or generic type (such as application/octet-stream) falls back to the file extension (.woff2, .woff, .ttf, .otf). SVGs must have an unprefixed <svg> root (prefixed roots such as svg:svg are rejected) and are rejected if they contain scripts, foreignObject, event handlers, entities or references to external resources.
API
POST /api/v2/branding/uploads/{kind} with a multipart file field and the update:branding scope returns (413 if the body is over the size limit, 400 for invalid files):
{
"url": "...",
"key": "tenants/acme/branding/logo/<uuid>.png",
"content_type": "image/png",
"size": 1234
}