Onboarding

Onboarding is owned by Central Auth. Platforms choose a mode in the platform registry; the gateway evaluates status on every login and embeds the result in the handoff exchange.

Modes

Mode	After central callback	Who hosts the UI
`none`	Immediate handoff	No onboarding gate
`platform`	Immediate handoff (status may be incomplete)	Platform UI
`central`	Incomplete → Account Center; complete → handoff	Account Center, then `/v1/auth/resume`

Mode comes from platforms.default_onboarding_mode. The optional onboardingMode query on /v1/auth/start must match that value when provided.

central additionally requires platforms.central_onboarding_enabled = true. Bootstrap exposes this to clients as onboarding.canCompleteCentrally.

Status model

Server-calculated statuses:

NOT_STARTED
IN_PROGRESS
COMPLETE

COMPLETE means every active required field has a value and user_platforms.completed_requirement_version equals the platform’s current requirement_version. Changing field definitions bumps requirement_version and moves previously complete memberships back to IN_PROGRESS.

The handoff payload includes:

json

{
  "status": "IN_PROGRESS",
  "requirementVersion": 4,
  "missingFields": ["dateOfBirth", "federationId"],
  "canCompleteCentrally": true
}

User-facing onboarding APIs

Authenticated with gateway cookie or ZITADEL Bearer (platforms use the cookie + exchanged gatewayToken):

Method	Path	Purpose
`GET`	`/v1/onboarding/{platformKey}/requirements`	Active fields + `currentValue` + `requirementVersion`
`GET`	`/v1/onboarding/{platformKey}/status`	Calculated status + `missingFields`
`PUT`	`/v1/onboarding/{platformKey}/values`	Submit field map; returns updated requirements
`POST`	`/v1/onboarding/{platformKey}/complete`	Mark complete only if server status has no missing fields

Completion with missing required values → 409 (Onboarding is incomplete: …).

Rendering guidance

Render fields in sortOrder
Map fieldType to a known safe component
Treat uiConfig as display hints only (no HTML / executable content)
PROFILE_FIELD values update canonical profile columns; CUSTOM_FIELD values are stored as JSONB per definition

IESF Card implementation

The Card frontend implements the central-mode page at:

text

/onboarding/{platformKey}?resume={transactionId}

/onboarding redirects to the Card application's configured AUTH_PLATFORM_KEY for direct visits. The central flow always uses the explicit platform-key URL supplied by the gateway.

The page has a deliberately minimal admin-aligned layout: global header, page heading, dynamic fields, and one continue action. It does not show the Account Center sidebar or wrap the form in an additional card. It supports all field types in the API schema, orders them by sortOrder, and applies only the safe width and help-text hints from uiConfig.

On submit, the frontend sends typed values to PUT .../values, then calls POST .../complete. It navigates to /v1/auth/resume?transaction=... only when the completion response is COMPLETE; the gateway re-evaluates status again before issuing the handoff. This page runs before the Card receives its platform session, so calls go to the Central Gateway with credentials: include and rely on the gateway HttpOnly cookie.

For the complete frontend flow, field mapping, deployment requirements, failure behavior, and operational checklist, see Central onboarding.

PUT / POST with cookie auth require Origin ∈ CORS_ORIGINS. Design platform-hosted onboarding as credentialed browser calls from an allowlisted origin.

Central mode resume

After Account Center completion, the browser navigates to:

http

GET /v1/auth/resume?transaction={transactionId}

The gateway binds the transaction to the authenticated gateway-session user, re-runs bootstrap, and issues the handoff only when status is COMPLETE. Incomplete users are sent back to:

text

{ACCOUNT_CENTER_URL}/onboarding/{platformKey}?resume={transactionId}

Field CRUD lives under /v1/platforms/{platformKey}/onboarding/fields and requires onboarding:schema:read / onboarding:schema:write (plus platform claim checks unless platforms:admin). These are operational APIs, not part of the login handoff.

Operators typically manage them from the IESF Card UI — see Admin operations (IESF Card).

Onboarding ​

Modes ​

Status model ​

User-facing onboarding APIs ​

Rendering guidance ​

IESF Card implementation ​

Cookie writes ​

Central mode resume ​

Schema administration (not for ordinary BFF login) ​

Related pages ​