Auth quickstart

Minimal steps to add SumX auth to a Next.js Pages Router app.

1. Install packages

pnpm add @sumx/ssr-auth-core @sumx/ssr-auth-react @sumx/ui

Match versions from Consume overview. Install peers: react-oidc-context, oidc-client-ts, @tanstack/react-query, lucide-react, lottie-web.

2. Environment

NEXT_PUBLIC_AUTHORITY=https://your-idp
NEXT_PUBLIC_CLIENT_ID=your-client-id
NEXT_PUBLIC_API_URL=https://your-api
AUTH_SESSION_SECRET=long-random-string
AUTH_ALLOWED_ORIGINS=http://localhost:3000

3. API routes

Create thin handlers:

• pages/api/auth/session.ts → createAuthSessionHandler
• pages/api/auth/logout.ts → createAuthLogoutHandler
• pages/api/auth/oidc-well-known.ts → createAuthOidcWellKnownHandler

Copy patterns from ssr-auth-core and the portal repo.

4. _app.tsx

1. AuthProvider from react-oidc-context (single root instance).
2. CheckTokenDepsProvider + CheckToken around protected routes.
3. SumxUiPermissionProvider for @sumx/ui (optional but recommended).

5. Verify

pnpm exec tsc --noEmit
pnpm test
pnpm run build

Smoke test: login → refresh → logout → cross-tab session dialog.

Next: Auth integration (advanced)