Authentication Guide

Overview

The recommended integration path is OAuth 2.0 Authorization Code flow with OIDC claims and PKCE where appropriate. Public-user hosted auth and social login feed into that same authorization flow.

Design, UI, and UX rules for those hosted auth surfaces now defer to the shared General Design System.

Current Authentication Methods

• Email and password
• Magic links
• PIN verification on selected login attempts
• Google
• Facebook

Apple Sign In and passkeys are planned backlog work and are not active today.

OAuth Flow

1. Redirect the user to /api/oauth/authorize.
2. User authenticates on the hosted SSO login surface.
3. SSO checks or creates the user’s app-permission state.
4. SSO redirects back with an authorization code.
5. Your backend exchanges that code at /api/oauth/token.

Important Distinction

Public-auth endpoints and OAuth endpoints are not interchangeable:

• /api/public/login creates a cookie-backed public session.
• /api/oauth/token issues OAuth tokens.

If your application needs bearer tokens, use the OAuth flow. If your shared-domain UI only needs hosted session validation, use the public session endpoints.

Social Login Security

Google and Facebook callbacks use a canonical encoded state payload tied to the signed CSRF cookie. After successful callback validation, the callback CSRF cookie is cleared to reduce replay value.