cross-domain-auth API

Seamless single-sign-on between helloworlddao.com and founderyos.dev via one-time token exchange. Authenticated DAO users click "Switch to FOS" and arrive on FounderyOS fully logged in — no re-authentication.

Services: oracle-bridge (mint + exchange) · founderyos-api (receiver) · @hello-world-co-op/auth@0.14.0 (frontend helper) Epic: PLATFORM-003 (completed 2026-04-20)

For the full reference including all endpoints, schemas, sequence diagram, security model, audit log, env vars, and error table, see the root API reference at api/cross-domain-auth.md.

Quick Reference

Endpoints

Method	Service	Path	Purpose
POST	oracle-bridge	/api/auth/cross-domain-token	Mint single-use token (session-authed + CSRF)
POST	oracle-bridge	/api/auth/exchange-token	Consume token, return user profile (service-token auth, server-to-server)
POST	founderyos-api	/api/v1/auth/cross-domain-login	Receive token, establish FOS session (browser-facing)

Authentication

• Mint: session cookie + X-CSRF-Token header (browser-initiated)
• Exchange: Authorization: Bearer <CROSS_DOMAIN_SERVICE_TOKEN> (server-to-server; token is a shared secret set identically on both oracle-bridge and founderyos-api)
• Cross-domain-login: no server-to-server auth required from the browser; founderyos-api authenticates to oracle-bridge internally

Exchange Response Contract

All downstream PLATFORM-003 consumers mock against these 9 fields — changing field names is a breaking change:

Field	Type	Nullable
user_id	UUID string	No
email	string	No
display_name	string	Yes
ic_principal	string	Yes
roles	string[]	No
entry_product	"dao" | "fos" | "lighthouse"	No
target_domain	string	No
issued_at	ms-epoch int	No
expires_at	ms-epoch int	No

Frontend Helper

import { navigateCrossDomain, CrossDomainAuthError } from '@hello-world-co-op/auth';

await navigateCrossDomain('founderyos.dev', '/dashboard', { entryProduct: 'dao' });
// throws CrossDomainAuthError with code:
// 'session-expired' | 'invalid-target' | 'network-error' | 'mint-failed' | 'missing-dom'

Related

• Repository — oracle-bridge
• Repository — founderyos-api
• Repository — auth package
• Full API reference
• payment-gateway — peer off-chain microservice reference for auth pattern