Branding

Customize auth page appearance with logos, colors, fonts, and CSS overrides per organization.

The branding system allows you to customize the visual appearance of Authsome's authentication pages on a per-organization basis. Each organization can define its own logo, color scheme, fonts, and custom CSS, creating a white-labeled experience for their users.

BrandingConfig entity

type BrandingConfig struct {
    ID              id.BrandingConfigID `json:"id"`
    OrgID           id.OrgID            `json:"org_id"`
    AppID           id.AppID            `json:"app_id"`
    LogoURL         string              `json:"logo_url,omitempty"`
    PrimaryColor    string              `json:"primary_color,omitempty"`
    BackgroundColor string              `json:"background_color,omitempty"`
    AccentColor     string              `json:"accent_color,omitempty"`
    FontFamily      string              `json:"font_family,omitempty"`
    CustomCSS       string              `json:"custom_css,omitempty"`
    CompanyName     string              `json:"company_name,omitempty"`
    Tagline         string              `json:"tagline,omitempty"`
    CreatedAt       time.Time           `json:"created_at"`
    UpdatedAt       time.Time           `json:"updated_at"`
}

OrgID — the organization this branding applies to. Each organization can have one branding config per app.
AppID — the application this branding is scoped to.
All color fields accept standard CSS color values (hex, rgb, hsl).
Branding config IDs have the prefix abrd_.

Configuration fields

Field	Type	Description	Example
`LogoURL`	`string`	URL to the organization's logo image	`https://cdn.example.com/logo.svg`
`PrimaryColor`	`string`	Primary brand color (buttons, links)	`#2563eb`
`BackgroundColor`	`string`	Page background color	`#f8fafc`
`AccentColor`	`string`	Accent color (highlights, focus rings)	`#7c3aed`
`FontFamily`	`string`	Font family for text	`"Inter", sans-serif`
`CustomCSS`	`string`	Raw CSS overrides	See below
`CompanyName`	`string`	Organization name displayed on auth pages	`Acme Corp`
`Tagline`	`string`	Short tagline under the logo	`Secure. Simple. Fast.`

Creating a branding config

Via HTTP API

POST /v1/auth/branding

{
  "org_id": "aorg_01jb...",
  "app_id": "myapp",
  "logo_url": "https://cdn.acme.com/logo.svg",
  "primary_color": "#2563eb",
  "background_color": "#ffffff",
  "accent_color": "#7c3aed",
  "font_family": "\"Inter\", system-ui, sans-serif",
  "company_name": "Acme Corp",
  "tagline": "Welcome to Acme"
}

Response:

{
  "id": "abrd_01jb...",
  "org_id": "aorg_01jb...",
  "app_id": "aapp_01j9...",
  "logo_url": "https://cdn.acme.com/logo.svg",
  "primary_color": "#2563eb",
  "background_color": "#ffffff",
  "accent_color": "#7c3aed",
  "font_family": "\"Inter\", system-ui, sans-serif",
  "company_name": "Acme Corp",
  "tagline": "Welcome to Acme",
  "created_at": "2024-11-01T10:00:00Z",
  "updated_at": "2024-11-01T10:00:00Z"
}

Via Go SDK

import "github.com/xraph/authsome/formconfig"

branding := &formconfig.BrandingConfig{
    OrgID:           orgID,
    AppID:           appID,
    LogoURL:         "https://cdn.acme.com/logo.svg",
    PrimaryColor:    "#2563eb",
    BackgroundColor: "#ffffff",
    AccentColor:     "#7c3aed",
    FontFamily:      `"Inter", system-ui, sans-serif`,
    CompanyName:     "Acme Corp",
    Tagline:         "Welcome to Acme",
}

err := engine.CreateBrandingConfig(ctx, branding)

CSS variable overrides

The Authsome UI renders auth pages using CSS custom properties. When a branding config is applied, these variables are set on the page root:

:root {
  --authsome-primary: #2563eb;
  --authsome-background: #ffffff;
  --authsome-accent: #7c3aed;
  --authsome-font-family: "Inter", system-ui, sans-serif;
}

Available CSS variables

Variable	Maps to	Default
`--authsome-primary`	`PrimaryColor`	`#18181b`
`--authsome-primary-foreground`	Auto-computed	`#ffffff`
`--authsome-background`	`BackgroundColor`	`#ffffff`
`--authsome-accent`	`AccentColor`	`#7c3aed`
`--authsome-accent-foreground`	Auto-computed	`#ffffff`
`--authsome-font-family`	`FontFamily`	`system-ui, sans-serif`
`--authsome-border-radius`	N/A (use CustomCSS)	`0.5rem`
`--authsome-input-background`	N/A (use CustomCSS)	`#f4f4f5`
`--authsome-input-border`	N/A (use CustomCSS)	`#e4e4e7`
`--authsome-error`	N/A (use CustomCSS)	`#dc2626`

Custom CSS

For more granular control, use the CustomCSS field to inject arbitrary CSS:

{
  "custom_css": ":root { --authsome-border-radius: 0.75rem; --authsome-input-background: #f0f9ff; } .authsome-card { box-shadow: 0 4px 24px rgba(0,0,0,0.08); } .authsome-logo { max-height: 48px; }"
}

Note: Custom CSS is sanitized to prevent XSS. <script> tags, url() with data URIs, expression(), and other potentially dangerous patterns are stripped.

Per-organization branding

In a multi-tenant setup, different organizations see different branding when their users sign in. The Authsome UI resolves branding by:

Checking the URL for an organization slug (e.g., auth.myapp.com/org/acme/login)
Looking up the organization by slug
Fetching the BrandingConfig for that organization and app
Applying the CSS variables and logo to the auth page

If no branding config exists for the organization, the default app styling is used.

Example: two organizations, different branding

// Acme Corp branding (blue theme)
acmeBranding := &formconfig.BrandingConfig{
    OrgID:        acmeOrgID,
    AppID:        appID,
    PrimaryColor: "#2563eb",
    LogoURL:      "https://cdn.acme.com/logo.svg",
    CompanyName:  "Acme Corp",
}

// Globex branding (green theme)
globexBranding := &formconfig.BrandingConfig{
    OrgID:        globexOrgID,
    AppID:        appID,
    PrimaryColor: "#16a34a",
    LogoURL:      "https://cdn.globex.com/logo.svg",
    CompanyName:  "Globex Corporation",
}

Updating branding

PATCH /v1/auth/branding/:brandingId

{
  "primary_color": "#dc2626",
  "tagline": "New tagline here"
}

Only fields included in the request are updated. Other fields remain unchanged.

Method	Path	Description
`POST`	`/branding`	Create a branding configuration
`GET`	`/branding`	Get branding for an org/app
`GET`	`/branding/resolve`	Resolve branding by org slug (for UI)
`GET`	`/branding/:brandingId`	Get branding by ID
`PATCH`	`/branding/:brandingId`	Update branding fields
`DELETE`	`/branding/:brandingId`	Delete a branding configuration