Headless Auth Server Mode: Keep OAuth, Own the UI
Hosted auth pages are a great default until product teams need app-native authorize screens, experiments, and app-owned signup fields. Headless mode in SqlOS keeps the auth server in SqlOS while your app owns the UI.
By SqlOS Team
Hosted auth pages are a great default.
They get a working login and signup experience in front of users quickly, and they keep the browser auth flow in one place.
But serious product teams tend to hit the same wall:
- the authorize popup does not match the real app
- signup experiments fight the hosted surface
- product teams want app-owned fields and conversion tuning
- “bring your own UI” often turns into custom bridge code
That is exactly why we built Headless Auth Server Mode in SqlOS.
The problem with most auth products
Most auth systems force a binary choice:
- Use the hosted page.
- Rebuild the auth UX yourself.
The first path preserves protocol correctness, but often limits product control.
The second path gives teams control over the UI, but it also tempts them into rebuilding:
- authorization request handling
- redirect validation
- PKCE state
- callback orchestration
- auth code issuance
That is where “pretty popup, weird auth plumbing” starts.
The boundary we actually wanted
We wanted a cleaner split:
- SqlOS still owns
/authorize - SqlOS still owns
/token - SqlOS still validates PKCE and redirect URIs
- SqlOS still runs OIDC and SAML callbacks
- SqlOS still issues the real auth code and tokens
- your app owns the UI
That is headless mode.
It is not “replace SqlOS auth with custom auth.”
It is:
- SqlOS owns the protocol
- your app owns the presentation
Why this matters for OAuth-powered MCP
For products using Emcy or other modern OAuth clients, the authorize popup is part of the product.
If the popup feels like a generic hosted page on another system, the integration feels bolted on.
With headless mode:
- the OAuth client still talks to your SqlOS authorization server
- the standards-facing metadata and token flow stay the same
- the popup can look like your product instead of generic auth chrome
That is a much better fit for serious app-owned AI and MCP products.
The example we wanted to prove
We upgraded the SqlOS example app to show the pattern directly:
- a side-by-side hosted vs headless story
- a real custom authorize shell at
/auth/authorize - a custom signup field called
referralSource - app-owned persistence of that field in
OnHeadlessSignupAsync - a signed-in app card that reads the value back through the normal product API
That last part matters.
It shows that headless mode is not just about prettier HTML. It is about giving product teams a place to own the data and UX that belong to the product while SqlOS keeps the authorization server correct.
Our view
Hosted auth should remain the default. It is the right choice for many teams.
But the more honest decision is not:
- hosted page vs completely custom auth server
It is:
- hosted page vs headless authorization server
That is the product boundary we think the market has been missing.
If you want the implementation guide, read Headless Auth.
If you want the exact consumer-app lifecycle with real snippets from the SqlOS Example app, read Headless Auth How-To.
If you want the product decision guide, read Hosted vs Headless Auth.