Start a new flow

Resolves a flow definition based on purpose + audience context and returns the first capability step. Creates a new session implicitly unless `session_id` is provided (for step-up / reauth on an existing session). The response contains an `id` field — the flow handle. Use it as the path parameter for all subsequent `/flow/{id}/submit` and `/flow/{id}/event` calls. The response also sets an encrypted `HttpOnly` cookie (`_zflow`) containing the flow's orchestration state (current step, collected data, history). The server is stateless between requests — all flow state lives in this cookie. The browser sends it automatically on subsequent requests.

Resolves a flow definition based on purpose + audience context and returns the first capability step. Creates a new session implicitly unless session_id is provided (for step-up / reauth on an existing session).

The response contains an id field — the flow handle. Use it as the path parameter for all subsequent /flow/{id}/submit and /flow/{id}/event calls.

The response also sets an encrypted HttpOnly cookie (_zflow) containing the flow's orchestration state (current step, collected data, history). The server is stateless between requests — all flow state lives in this cookie. The browser sends it automatically on subsequent requests.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

project_id*project-id

purpose*string

flow_definition_name?string

Name of a specific flow definition to use. When omitted, the engine selects the best-matching definition based on purpose + audience context.

dry_run?boolean

Set to true to simulate the flow without actually creating any user or session. Useful for testing and validation of flow definitions. This requires setting the flow_definition_name property as well.

schema_version?string

Semver version of the flow definition JSON Schema to use. When omitted, the latest version is used.

challenge_nonce?challenge-nonce

Origin-bound, single-use nonce obtained from POST /bootstrap/challenge. Binds the request to the browser that initiated the flow, preventing cross-origin replay.

session_id?string

Existing session to attach to (for step-up / reauth). Omit to let the flow create a new session implicitly.

auth_request_id?string

OIDC/SAML auth request ID (links flow to protocol request).

redirect_uri?string

hint?

Response Body

`application/json`

curl -X POST "https://example.com/flow" \  -H "Content-Type: application/json" \  -d '{    "project_id": "river-8421",    "purpose": "login"  }'

{  "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": {}}

Start a new flow

Request Body

Response Body

201application/json

400application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`