IESF Central Auth Gateway

English integration documentation for platform teams that connect to the Central Auth Gateway (this backend). It describes only the backend contracts and flows you must implement. It does not document any specific frontend application.

What this service is

The Central Auth Gateway is the only platform-facing OIDC client for IESF platforms. ZITADEL remains the authentication authority (credentials, login/registration, MFA/passkeys, OIDC tokens). This service owns:

• platform routing and registry
• JIT local user / profile provisioning
• onboarding evaluation
• opaque gateway browser sessions
• one-time platform handoffs

API instances are stateless. PostgreSQL stores profile, onboarding, authentication transactions, gateway sessions, and handoffs.

What platforms implement

A platform never becomes a ZITADEL application and never receives a ZITADEL access token, refresh token, ID token, PKCE verifier, or nonce.

Your platform surface against Central Auth is deliberately small:

Step	Who	Endpoint / action
1	Browser	Redirect to GET /v1/auth/start
2	Gateway + ZITADEL	Login / registration (opaque to the platform)
3	Browser	Lands on your registered callback_url with code=handoff_…
4	Your BFF	POST /v1/auth/exchange with platform Basic credentials
5	Your BFF	Create your own local session from the exchange body

How to read this guide

1. Architecture — responsibility boundaries and system shape
2. Authentication flow — full start → callback → handoff / resume sequences
3. Platform integration — checklist your BFF must satisfy
4. Admin operations (IESF Card) — register platformKey and onboarding fields in Card
5. Onboarding — none / platform / central modes and APIs
6. Central onboarding — Account Center UI, dynamic field rendering, completion, and resume
7. Security invariants — rules that must not be violated
8. API reference — endpoint map and exchange JSON (runtime-accurate)

Live machine-readable contracts stay on the running API: OpenAPI 3.1 at /openapi.json, Swagger UI at /docs. Where narrative docs and runtime diverge, runtime wins; known divergences are called out explicitly.