Central onboarding

Central onboarding is the gateway-controlled completion flow used when a platform requires profile data before it receives a handoff. The IESF Card Account Center hosts the user interface, while the Central Auth Gateway remains authoritative for the schema, values, completion state, and continuation of the login transaction.

This page documents the complete central-mode flow and the Card frontend implementation. For the shared status model and the other onboarding modes, see Onboarding.

When the flow runs

A platform enters this flow when all of the following are true:

• default_onboarding_mode is central
• central_onboarding_enabled is true
• the gateway-calculated onboarding status is not COMPLETE

The gateway does not issue a platform handoff at this point. After the ZITADEL callback it creates an HttpOnly gateway session and redirects the browser to:

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

The platformKey selects the server-managed field schema. The opaque resume UUID identifies the original authentication transaction; it is not proof that onboarding is complete.

End-to-end sequence

If the resume-time evaluation is still incomplete, the gateway redirects the browser back to the Card onboarding page. Client-side state never bypasses this check.

Frontend routes and layout

The Card frontend exposes two routes:

Route	Behavior
/onboarding/{platformKey}?resume={transactionId}	Canonical central-login route supplied by the gateway
/onboarding	Convenience route that redirects to the configured AUTH_PLATFORM_KEY

The page intentionally has a minimal admin-aligned layout:

• shared global IESF header
• central onboarding eyebrow, title, and short description
• schema-driven fields without an extra card frame
• one primary Save and continue action
• inline loading, validation, and upstream-error states

It does not render the Account Center sidebar because central onboarding happens before the Card receives and exchanges the platform handoff.

Loading and rendering requirements

The frontend requests:

GET /v1/onboarding/{platformKey}/requirements

The response supplies requirementVersion, active field definitions, and each field's currentValue. The frontend sorts fields by sortOrder and maps fieldType as follows:

API field type	Control and submitted value
TEXT	Text input → string
TEXTAREA	Multiline input → string
NUMBER	Number input → number
BOOLEAN	Checkbox → boolean
DATE	Date input → YYYY-MM-DD string
SELECT	Single select → option value
MULTI_SELECT	Checkbox group → string array
COUNTRY	Two-letter text input → uppercase country code
PHONE	Telephone input → international phone string
EMAIL	Email input → string
URL	URL input → string

Empty scalar values are submitted as null; an empty multi-select is submitted as []. Required fields are marked visually, while the gateway performs the authoritative dynamic validation.

The frontend uses only safe schema metadata:

• label, placeholder, and description
• validation.minLength, validation.maxLength, validation.min, and validation.max
• options for select controls
• uiConfig.width for grid width
• uiConfig.helpText for supporting text

uiConfig is never interpreted as HTML or executable content.

Save, complete, and resume

Submission is deliberately sequential:

1. Convert browser form values to their documented API types.
2. Send the complete field map to PUT /v1/onboarding/{platformKey}/values.
3. Call POST /v1/onboarding/{platformKey}/complete.
4. Require the returned status to be COMPLETE.
5. Navigate the browser to GET /v1/auth/resume?transaction={transactionId}.

The frontend does not append completed=true or treat a successful value write as completion. The completion endpoint verifies all active required fields, and the resume endpoint repeats the server-side evaluation before issuing a handoff.

When the page is opened without a valid resume UUID, it can still save onboarding details for an authenticated gateway session. After completion it returns the user to /profile instead of resuming an authentication transaction.

Authentication, cookies, and CORS

Central onboarding API calls use credentials: include and authenticate with the HttpOnly gateway cookie established during the central callback. The credential is not exposed to Card JavaScript and is not the Card platform session cookie.

Deployment must satisfy all of these conditions:

• AUTH_BACKEND_URL in the Card frontend points to the Central Gateway API including /v1
• ACCOUNT_CENTER_URL in the gateway points to the public Card origin
• the Card origin is included in gateway CORS_ORIGINS
• credentialed CORS responses return the exact allowed origin, not *
• Card and gateway hosts have a same-site/cookie arrangement compatible with the gateway cookie's SameSite and Secure attributes
• production uses HTTPS

Cookie-authenticated PUT and POST requests are also protected by the gateway's allowed-origin check.

Error and retry behavior

Failure	User-visible behavior
Requirements cannot be loaded	Inline error and Try again action
Browser-native field validation fails	Submission remains on the page and highlights the invalid control
Required multi-select is empty	Inline validation message before the API write
Value validation fails at the gateway	Gateway message shown above the form; entered values remain available
Completion returns incomplete	User remains on the form with an error
Session expired	Gateway rejects the request; the user must restart authentication
Resume evaluation is incomplete	Gateway redirects back to the same onboarding route

No failed request is treated as a successful completion, and values are never replaced with mock data.

Operational setup

Before testing a central flow:

1. Register the platform and its callback/return URL roots in Card Admin.
2. Set its default onboarding mode to central.
3. Enable central onboarding.
4. Add and activate the required field definitions in /admin/onboarding.
5. Configure ACCOUNT_CENTER_URL, AUTH_BACKEND_URL, CORS, HTTPS, and cookie-compatible hostnames.
6. Start authentication through /v1/auth/start for that platform.

Changing an active field definition increments the platform requirementVersion. Previously complete users become IN_PROGRESS and will see central onboarding again on their next central-mode authentication when they no longer satisfy the current schema.

Security invariants

• The platform key and onboarding policy come from the server-side registry.
• The resume transaction must be bound to the authenticated gateway-session user.
• The frontend never creates a handoff code.
• Only the gateway can mark the current requirement version complete.
• Resume re-checks the active platform, transaction, user, and onboarding state.
• Profile fields update canonical profile storage; custom fields remain platform-scoped.
• The gateway token and one-time handoff code are never stored in browser-readable application state.

Related pages

• Onboarding modes and status model
• Authentication flow
• Admin operations (IESF Card)
• Platform integration
• Security invariants
• API reference