Branding | XID

Customize the Hosted Auth appearance with colors, fonts, radius, logos, and custom CSS.

Branding options

Branding configuration controls the visual appearance of the Hosted Auth pages, consent screen, and email templates. Each organization can override the instance-level defaults.

Option	Description
Primary color	Main action color used for buttons, links, and focus rings. Accepts CSS hex or oklch values.
Background color	Page background for Hosted Auth screens.
Accent color	Secondary highlight color used for labels and decorative elements.
Border radius	Corner radius applied to cards, inputs, and buttons. Choose from none, small, medium, large, or full.
Font family	Google Fonts name or a custom CDN font URL. Falls back to the system sans-serif stack.
Logo (light)	PNG or SVG displayed on light-theme pages. Stored in R2.
Logo (dark)	PNG or SVG displayed on dark-theme pages. Falls back to the light logo when not set.

Per-organization branding

Each organization can override instance-level branding with its own logo, colors, and background. The Login Worker resolves brand configuration per organization, falling back to the instance defaults when no organization override is set. Brand cache reads complete in under 2 ms at P50.

Management API endpoint

Update organization branding with a PATCH request. Only fields present in the request body are changed. Pass null to clear a field and restore the parent default.

curl -X PATCH https://xid.dev/v1/organizations/org_xxx/branding \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "primary_color": "#6366f1",
    "border_radius": "medium",
    "font_family": "Inter",
    "hide_xid_branding": true
  }'

Custom CSS constraints

Maximum size is 50 KB per organization.
The CSP filter strips @import rules and url() references that point outside the allowlist. Only pure CSS property declarations survive.
External script execution from within custom CSS is blocked. Use the custom CSS only for visual overrides, not for behavioral logic.
Changes are previewed in an iframe sandbox before being published. Preview and live states are kept separate.

Email template branding

Transactional email templates (verification, magic link, OTP, password reset, and invitations) pick up the organization logo and primary color automatically. Custom email HTML templates can be uploaded per organization through the console.