Intégration WorkOS en mode headless : authentification UI custom sur Next.js

Intégration WorkOS en mode headless — UI d'authentification custom (sign-in / sign-up) sur Next.js 15

Roundtable est une plateforme SaaS B2B d'investissement (SPV, deals, fonds), construite en TypeScript strict sur Next.js 15 (App Router) + Node.js, avec tRPC, Tailwind et i18n fr/en (next-intl), dans un monorepo pnpm.

Contexte : L'authentification repose aujourd'hui sur WorkOS AuthKit en mode hébergé : la page de connexion est servie par WorkOS sur un domaine dédié. Méthodes actives : email/mot de passe, OAuth Google et LinkedIn.

Objectif : L'application va être servie sur plusieurs domaines — d'abord des sous-domaines clients (client1.roundtable.eu), puis des domaines entièrement custom (client1.com) — avec un white-label complet : chaque client doit avoir une page de connexion à son image. La page hébergée WorkOS n'autorisant qu'un branding global, la solution retenue est de construire notre propre UI de sign-in / sign-up en mode headless, hébergée dans l'app Next.js, branchée directement sur les API WorkOS User Management (aucun surcoût WorkOS, contrôle total du branding par domaine).

Périmètre de la mission

• Méthodes d'auth : email + mot de passe ; Magic Auth (code email) ; OAuth Google & LinkedIn (flux délégué à WorkOS) ; MFA/TOTP ; passkeys.

• Flux complets : inscription + vérification d'email (saisie de code), connexion, mot de passe oublié / réinitialisation, enrôlement + challenge MFA, organization picker, déconnexion.

• Gestion de session serveur : gestion du cookie + rotation du refresh token (reproduire le comportement de authkit-nextjs), intégration au middleware Next existant, compatibilité Server Components (withAuth) et Client Components (useAuth).

• Multi-domaine : redirect_uri / base URL host-aware validés contre une liste de domaines autorisés ; cookies isolés par host.

• Branding par domaine : UI de login thémable (couleurs + logo), résolue côté serveur et sans flash côté client.

• Qualité & sécurité : états d'erreur exhaustifs, i18n fr/en, responsive mobile-first, anti-bot / rate-limiting (clarifier la couverture WorkOS en headless), tests automatisés sur les flux critiques.

Livrables

- UI sign-in / sign-up complète, brandable par domaine.

- Couche d'intégration WorkOS headless + gestion de session serveur, compatible avec l'existant.

- Tests

Avoir déjà implémenté en production un flux d'authentification headless / UI custom avec WorkOS User Management.

Compétences indispensables

- Maîtriser WorkOS User Management en mode headless — expérience production prouvée

- Maîtriser Next.js 15 App Router : Server Components, Client Components, middleware, cookies.

- Maîtriser TypeScript.

- Connaître les bonnes pratiques d'internationalisation.

Compétences appréciées

- Connaître tRPC et React Query.

Stack : WorkOS User Management · Next.js 15 App Router · TypeScript strict · tRPC · Tailwind · next-intl · pnpm workspaces · Node.js/Express · Prisma/PostgreSQL · Playwright.