---
title: "Start Dynamic Auth Flow"
method: POST
path: "/v1/identities/dynamic/start/{session_id}"
tags: ["Identities"]
---

# Start Dynamic Auth Flow

`POST /v1/identities/dynamic/start/{session_id}`

## Request

- Base URL: `https://api.anchorbrowser.io`
- URL: `https://api.anchorbrowser.io/v1/identities/dynamic/start/{session_id}`
- Auth: API key in header `anchor-api-key`

Starts (or restarts) a dynamic auth flow in an existing browser session.
`session_id` is required in the path. Advances until the next presentation
(`decision`, `form`, `detection_failed`, `authenticated`, or `failed`).

If the response is `detection_failed` with `retryable: true`, or the request
times out, keep polling `GET /v1/identities/dynamic/state/{session_id}` —
some login steps take longer than a single start/resolve call. If
`detection_failed` and `retryable` is false, open `live_view_url` to finish
signing in. Do not treat a timeout as a hard stop until `view.type` is
`failed` or `detection_failed` and `retryable` is false.

## Path parameters

- `session_id` string, required

## Request body

- AuthFlowV2StartRequest
  - `url` string, uri, required: Landing URL to open in the session (login page).
  - `host` string, required: Hostname of `url`. Must match the URL hostname after normalization.

## Response `200`

First presentation of the auth flow

- union: Presentation returned by start/resolve. GET `/state` nests the same object as `view` when there is something to show. Discriminated on `type`. Call `/resolve` only for `decision` or `form`.
  - AuthFlowV2DecisionView
    - `session_id` string, required
    - `host` string, required: Hostname the flow was started for.
    - `current_step_label` string, required: Human-readable label of the current login step.
    - `step_id` string, required: Identifier of the current login step.
    - `cdp_url` string, required: CDP websocket URL of the session driving the login.
    - `live_view_url` string, required: URL to watch or take over the session in a browser.
    - `discovery_error` string: Set when automatic step detection hit an error. A partial flow may still be presented.
    - `type` 'decision', required
    - `options` AuthFlowV2DecisionOption[], required: Each item is `{ step_id, label, automatable }`. POST `/resolve` with `{ "choice": "<step_id>" }`.
      - `step_id` string, required: Opaque identifier for this option; pass it back as `choice`.
      - `label` string, required: Human-readable name of the login path (e.g. "Continue with Google").
      - `automatable` boolean, required: True if this path is known to be replayable unattended, without a human.
  - AuthFlowV2FormView
    - `session_id` string, required
    - `host` string, required: Hostname the flow was started for.
    - `current_step_label` string, required: Human-readable label of the current login step.
    - `step_id` string, required: Identifier of the current login step.
    - `cdp_url` string, required: CDP websocket URL of the session driving the login.
    - `live_view_url` string, required: URL to watch or take over the session in a browser.
    - `discovery_error` string: Set when automatic step detection hit an error. A partial flow may still be presented.
    - `type` 'form', required
    - `options` AuthFlowV2FormOption[], required: Each item includes `type` and `automatable`. POST `/resolve` with `{ "option_index": n, "values": { ... } }`.
      - `type` 'credentials' | 'mfa_totp' | 'mfa_sms' | 'mfa_email' | 'sso' | 'captcha' | 'consent' | 'magic_link' | 'passkey' | 'generic' | 'totp_secret' | 'gmail_one_click_integration', required
      - `automatable` boolean, required: True if this option can be replayed unattended without a human.
      - `inputs` object[]
        - `name` string, required
        - `type` string, required
        - `label` string
        - `placeholder` string
        - `value` string
      - `extra_data` object: Type-specific extras. Present only when the option has any.
        - `create_integration_url` string, uri: On `gmail_one_click_integration`. Browser URL to connect Gmail; see the option description for the token it returns.
        - `number` string: On `consent`. Device confirmation number from the live page, when shown.
      - `message` string
      - `provider` string
      - `phoneHint` string
    - `credentials_rejected` boolean: The last submission was rejected (e.g. wrong password) and the same form is re-presented.
    - `credentials_passed` boolean: The previous step just cleared. Transient.
  - AuthFlowV2DetectionFailedView
    - `session_id` string, required
    - `host` string, required: Hostname the flow was started for.
    - `current_step_label` string, required: Human-readable label of the current login step.
    - `step_id` string, required: Identifier of the current login step.
    - `cdp_url` string, required: CDP websocket URL of the session driving the login.
    - `live_view_url` string, required: URL to watch or take over the session in a browser.
    - `discovery_error` string: Set when automatic step detection hit an error. A partial flow may still be presented.
    - `type` 'detection_failed', required
    - `node_status` 'detected' | 'failed' | 'explored', required: How far the current step has been analyzed.
    - `last_error` string: The most recent navigation error, if any.
    - `retryable` boolean, required: True means keep polling `/state`; false means stop and use `live_view_url`.
    - `message` string, required: Why detection stopped. Open `live_view_url` to finish signing in in the browser. Do not resolve. If `retryable` is true, you may also poll GET `/state`.
  - AuthFlowV2AuthenticatedView
    - `session_id` string, required
    - `host` string, required: Hostname the flow was started for.
    - `current_step_label` string, required: Human-readable label of the current login step.
    - `step_id` string, required: Identifier of the current login step.
    - `cdp_url` string, required: CDP websocket URL of the session driving the login.
    - `live_view_url` string, required: URL to watch or take over the session in a browser.
    - `discovery_error` string: Set when automatic step detection hit an error. A partial flow may still be presented.
    - `type` 'authenticated', required
    - `message` string: Human-readable status. POST `/finalize` to persist the identity.
  - AuthFlowV2FailedView
    - `session_id` string, required
    - `host` string, required: Hostname the flow was started for.
    - `current_step_label` string, required: Human-readable label of the current login step.
    - `step_id` string, required: Identifier of the current login step.
    - `cdp_url` string, required: CDP websocket URL of the session driving the login.
    - `live_view_url` string, required: URL to watch or take over the session in a browser.
    - `discovery_error` string: Set when automatic step detection hit an error. A partial flow may still be presented.
    - `type` 'failed', required
    - `error` string, required: What went wrong.
    - `retryable` boolean, required: True means keep polling `/state`; false means stop.

## Other responses

- `400`: Invalid request or host does not match url hostname
- `404`: Session not found or not active
- `409`: Auth flow transition already in progress, or navigation/discovery failed
- `500`: Failed to start auth flow

## Changes

- **2026-10-16** `b3bfdb98c79e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/changes/v1/identities/dynamic/start/:session_id/post.md)

---

[API](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api.md) - [All operations](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/revisions/9d755f22df0e?raw)