Submit step data and advance

Submits user input for the current step. The server validates, processes (e.g., verifies a credential), advances the state machine through any invisible steps, and returns the next visible step. The response sets an updated encrypted `HttpOnly` cookie (`_zflow`) with the new flow state. The server is stateless — all orchestration state is carried in this cookie between requests. **Important:** The `id` in the response may differ from the `id` used in the request. This happens when a flow pivots (pushes a new flow onto the stack) or when a stacked flow completes (auto-pops to the parent flow). Always use the `id` from the latest response for the next request. ## Flow completion When `step.type` is `complete`, the flow is terminal. The `step.behavior` field tells the frontend what to do: | `behavior` | Action | |------------- |------------------------------------------------------------| | `redirect` | Navigate to `redirect_uri` (OIDC/SAML auth request done). | | `show` | Render the step as a success screen (e.g., registration). | A `complete` step is only returned when the **entire flow stack** is done. If a stacked flow (e.g., recovery pivoted from login) finishes, the server auto-pops to the parent flow and returns the parent's next step — the frontend never sees a `complete` for intermediate flows.

Submits user input for the current step. The server validates, processes (e.g., verifies a credential), advances the state machine through any invisible steps, and returns the next visible step.

The response sets an updated encrypted HttpOnly cookie (_zflow) with the new flow state. The server is stateless — all orchestration state is carried in this cookie between requests.

Important: The id in the response may differ from the id used in the request. This happens when a flow pivots (pushes a new flow onto the stack) or when a stacked flow completes (auto-pops to the parent flow). Always use the id from the latest response for the next request.

Flow completion

When step.type is complete, the flow is terminal. The step.behavior field tells the frontend what to do:

`behavior`	Action
`redirect`	Navigate to `redirect_uri` (OIDC/SAML auth request done).
`show`	Render the step as a success screen (e.g., registration).

A complete step is only returned when the entire flow stack is done. If a stacked flow (e.g., recovery pivoted from login) finishes, the server auto-pops to the parent flow and returns the parent's next step — the frontend never sees a complete for intermediate flows.

Path Parameters

id*string

Flow ID returned by POST /flow or the latest POST /flow/{id}/submit. Used to look up the correct flow state from the encrypted cookie, which can hold multiple concurrent flows. May change between responses when a flow pivot or pop occurs — always use the id from the latest response.

Header Parameters

Origin?string

Standard browser Origin header. When a step issues a passkey challenge, the server derives the WebAuthn relying-party id and the allowed origin from this value. Browsers send it automatically on the fetch POST; no client action is required.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

session_token?string

Reserved for future rotation. The sealed _zflow cookie carries the flow state today.

action*string

Which action to take. Must be a key from the step's actions dictionary:

A regular action (e.g., "submit", "register", "back")
The reserved value "sso" — triggers SSO redirect (requires sso_provider_id)

fields?

User input values. Keys match field names from the step's fields dictionary.

gate_proofs?

Solutions for security gates. Keys match gate names from the step's gates dictionary. The orchestrator collects these from <zl-captcha> component events.

challenge_response?

Response to a pending challenge on the step. Required when the step has a challenge property (e.g., after submitting a passkey action). The <zl-passkey> component populates this after the WebAuthn ceremony.

sso_provider_id?string

ID of the selected SSO provider (from sso_providers[].id). Required when action is "sso".

Response Body

`application/json`

curl -X POST "https://example.com/flow/flow_01H8Z/submit" \  --cookie "_zflow=string" \  -H "Content-Type: application/json" \  -d '{    "action": "string"  }'

{  "id": "flow_01H8Z",  "session_id": "string",  "session_token": "string",  "step": {    "name": "login",    "texts": {      "title_key": "login.title",      "description_key": "login.description"    },    "fields": [      {        "name": "email",        "type": "email",        "text_key": "login.field.email",        "required": true      },      {        "name": "password",        "type": "password",        "text_key": "login.field.password",        "required": true      }    ],    "actions": [      {        "name": "submit",        "kind": "submit",        "text_key": "login.action.submit",        "primary": true      },      {        "name": "register",        "kind": "navigate",        "text_key": "login.action.register"      },      {        "name": "recover",        "kind": "navigate",        "text_key": "login.action.recover"      }    ],    "gates": {      "captcha": {        "kind": "captcha",        "provider": "altcha",        "config": {          "algorithm": "SHA-256",          "challenge": "abc123",          "salt": "xyz789",          "max_number": 100000        }      }    },    "sso_providers": [      {        "id": "google-1",        "name": "Google",        "template": "google"      },      {        "id": "entra-1",        "name": "Microsoft",        "template": "entraid"      }    ]  },  "branding": {    "layout": "centered",    "liquid_template": "string",    "logo_url": "http://example.com",    "font_url": "http://example.com",    "hero_url": "http://example.com"  },  "redirect_uri": "http://example.com",  "handoff_token": "string",  "handoff_token_expires_at": "2019-08-24T14:15:22Z"}

{  "id": "flow_01H8Z",  "session_id": "string",  "session_token": "string",  "step": {    "name": "login",    "texts": {      "title_key": "login.title",      "description_key": "login.description"    },    "fields": [      {        "name": "email",        "type": "email",        "text_key": "login.field.email",        "required": true      },      {        "name": "password",        "type": "password",        "text_key": "login.field.password",        "required": true      }    ],    "actions": [      {        "name": "submit",        "kind": "submit",        "text_key": "login.action.submit",        "primary": true      },      {        "name": "register",        "kind": "navigate",        "text_key": "login.action.register"      },      {        "name": "recover",        "kind": "navigate",        "text_key": "login.action.recover"      }    ],    "gates": {      "captcha": {        "kind": "captcha",        "provider": "altcha",        "config": {          "algorithm": "SHA-256",          "challenge": "abc123",          "salt": "xyz789",          "max_number": 100000        }      }    },    "sso_providers": [      {        "id": "google-1",        "name": "Google",        "template": "google"      },      {        "id": "entra-1",        "name": "Microsoft",        "template": "entraid"      }    ]  },  "branding": {    "layout": "centered",    "liquid_template": "string",    "logo_url": "http://example.com",    "font_url": "http://example.com",    "hero_url": "http://example.com"  },  "redirect_uri": "http://example.com",  "handoff_token": "string",  "handoff_token_expires_at": "2019-08-24T14:15:22Z"}

{  "code": "string",  "message": "string",  "details": {}}

{  "code": "string",  "message": "string",  "details": {}}

Submit step data and advance

Flow completion

Path Parameters

Header Parameters

Cookie Parameters

Request Body

Response Body

200application/json

400application/json

409application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`