API reference

Narrative summary of platform-relevant endpoints. Authoritative request/response schemas live on the running service:

• OpenAPI 3.1: {CENTRAL_BASE}/openapi.json
• Swagger UI: {CENTRAL_BASE}/docs

Generate clients from OpenAPI. All operations have stable operationId values.

Authentication flow

Method	Path	Auth	operationId	Notes
GET	/v1/auth/start	Public	startAuthentication	Browser entry; 302 to ZITADEL
GET	/v1/auth/callback	Public (ZITADEL only)	handleZitadelCallback	Fixed central redirect URI; sets gateway cookie
GET	/v1/auth/resume	Gateway cookie	resumeAuthentication	Central onboarding continuation
POST	/v1/auth/exchange	Platform Basic	exchangeAuthenticationHandoff	Server-to-server; one-time handoff_ code

Start query parameters

Param	Required	Rules
platformKey	yes	^[A-Z][A-Z0-9_]{1,63}$
returnTo	yes	1–2048 chars; allowlisted
onboardingMode	no	none | platform | central; must match registry

Exchange body

{ "code": "handoff_…" }

code must start with handoff_ (max length 200).

Exchange 200 body (runtime)

Returned by HandoffService.exchange:

Field	Type	Meaning
session.id	uuid	Gateway session id
session.expiresAt	date-time	Session expiry
session.gatewayToken	string	Opaque credential for Central cookie auth
user.id	uuid	Local user id
user.sub	string	ZITADEL subject
platform.key	string	Platform key
onboarding.status	enum	NOT_STARTED | IN_PROGRESS | COMPLETE
onboarding.requirementVersion	integer	Current platform requirement version
onboarding.missingFields	string[]	Required field keys still empty
onboarding.canCompleteCentrally	boolean	From platform central_onboarding_enabled
permissions	string[]	Captured gateway session permissions
returnTo	string	Absolute allowlisted destination from start

OpenAPI’s handoffExchangeSchema reuses a bootstrap user shape that may list optional picture. Runtime exchange does not currently return picture. Prefer the table above.

Typical status codes (auth-flow)

Code	When
302	Successful start / callback / resume redirect
400	Validation / invalid redirect shape
401	Bad platform Basic auth; ZITADEL exchange failures; missing gateway cookie on resume
403	returnTo or onboardingMode not registered for platform
404	Unknown platform; invalid/expired/consumed state or handoff
409	Platform callback missing; central onboarding disabled; documented resume conflict when a handoff row already exists for the transaction (unique on transaction_id)
503	OIDC client not configured; ZITADEL unavailable

Onboarding (user)

Method	Path	Auth	Purpose
GET	/v1/onboarding/{platformKey}/requirements	User (Bearer or gateway cookie)	Fields + current values
GET	/v1/onboarding/{platformKey}/status	User	Calculated status
PUT	/v1/onboarding/{platformKey}/values	User	Upsert values (cookie writes need allowlisted Origin)
POST	/v1/onboarding/{platformKey}/complete	User	Complete when no missing required fields

Platform registry (admin)

Requires platforms:admin (via gateway session permissions or ZITADEL Bearer with that role).

Method	Path	Notes
GET / POST	/v1/platforms	List / create
GET / PATCH / DELETE	/v1/platforms/{platformKey}	Read / update / soft deactivate
POST	/v1/platforms/{platformKey}/activate	Re-activate
POST	/v1/platforms/{platformKey}/credentials/rotate	Returns new secret once

Onboarding schema (admin)

Under /v1/platforms/{platformKey}/onboarding/fields with onboarding:schema:read / onboarding:schema:write. Non-central callers must also carry a matching platform claim unless they have platforms:admin.

Profile / account (Account Center style)

Not required for basic platform login, but available with user auth:

• GET /v1/me
• GET / PATCH /v1/profile/me
• POST /v1/profile/me/avatar/upload-request
• GET /v1/account/authentication-methods
• POST /v1/account/password
• DELETE /v1/account/me (soft delete)

Health

Method	Path	Behavior
GET	/health/live	No dependency checks
GET	/health/ready	Checks PostgreSQL

Security schemes (OpenAPI)

• platformBasicAuth — exchange only
• gatewayCookieAuth — resume and cookie-authenticated user routes
• Bearer ZITADEL access token — user and admin routes when not using the gateway cookie

Related pages

• Platform integration
• Authentication flow
• Security invariants