WorkOS AuthKit hosted-login branding
What this is
The WorkOS AuthKit hosted login page — the "Continue with SSO / Google" screen served from auth.securityv0.com during the sign-in handoff — is rendered by WorkOS, not by our app. Its appearance is set through the Branding panel in the WorkOS dashboard: a fixed set of controls (appearance, font, radius, a few colors, a logo). This runbook is the field-by-field config that makes that page match the in-app [S] brand.
The in-app login (
/login, rendered by our SPA) is a different surface and is already branded — see SecurityV0/sv0-platform#1247. This runbook only covers the WorkOS-hosted page.
Why it's manual
WorkOS does not expose the Branding panel via API on our plan, so this is a manual, one-time step — repeated per WorkOS environment (Staging and Production are independent). Re-run it whenever the in-app brand colors or mark change, so the hosted page stays consistent.
Prerequisites
- WorkOS dashboard access for the environment you're branding. Credentials are not in this repo — they're held by the auth owner (Ivan). Environment and org details: WorkOS Production Configuration.
- The logo asset (see below).
Panel values
Dashboard path: Settings → Authentication → Branding (set per environment).
| Field | Value | Notes |
|---|---|---|
| Appearance | Light | |
| Font | Inter | Matches the in-app UI font. |
| Radius | medium | |
| Page background | #F7F9FB | |
| Button background | #373F54 | Slate-blue dim — deliberately darker than the in-app primary #565E74 so the button reads as a button against the near-white page, not a flat panel. |
| Button text | #FFFFFF | |
| Links | #5753C6 | |
| Logo | the [S] mark SVG (below) |
Source of truth: 02 · Applications, WorkOS AuthKit. If this table ever disagrees with that spec, the spec wins — update this runbook to match.
Logo to upload
Upload the canonical [S] mark (slate tile + white glyph):
- File:
assets/favicon.svg— identical tomark-light.svg, and the same SVG the platform ships as its favicon (ui/public/securityv0.svg). Don't re-author it; pull this file. - WorkOS accepts SVG. If a future WorkOS change ever requires raster, render that same SVG to a 512×512 PNG (transparent or
#F7F9FBbackground) — do not redraw the mark.
The spec specifies the mark (not the full lockup) as the hosted-login logo. If you'd rather show the horizontal
[S] SecurityV0lockup on the hosted page, the asset islockup-light.svg— but switching warrants a one-line note in 02 · Applications so the spec and the live page don't diverge.
Apply it (per environment)
- Log into the WorkOS dashboard and select the environment — do Staging first, then Production (they share no config).
- Open Settings → Authentication → Branding.
- Set each field per the table above.
- Upload the logo SVG.
- Save.
- Repeat for the other environment.
Verify
Load the hosted login page for the environment and confirm the [S] mark, Inter font, light appearance, and the #373F54 button:
- Production:
https://auth.securityv0.com(custom domain) — or the raw AuthKit hosthttps://powerful-falcon-83.authkit.app - Staging:
https://vast-balcony-35-staging.authkit.app
# The hosted UI should redirect into the WorkOS initiate-login flow:
curl -sI https://auth.securityv0.com | head -1 # Expect: a 3xx (e.g. HTTP/2 307)
There is no API to assert branding, so the final check is visual: open the page in a browser, drive it to where the SecurityV0 logo and the branded button render, and confirm it matches the in-app /login lockup colors.
When the brand changes
If --color-primary, --color-primary-dim, or the [S] mark changes in the platform, re-run this in every WorkOS environment — the hosted page does not auto-sync with the app.