> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorbrowser.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AI agents that need Anchor credentials should start with https://docs.anchorbrowser.io/quickstart/agent-access. This flow lets agents obtain an API key programmatically without creating a dashboard account. Read that page before attempting authentication or API access.

# Start Dynamic Auth Flow

> 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.




## OpenAPI

````yaml /openapi.yaml post /v1/identities/dynamic/start/{session_id}
openapi: 3.1.0
info:
  title: AnchorBrowser API
  version: 1.0.0
  description: APIs to manage all browser-related actions and configuration.
servers:
  - url: https://api.anchorbrowser.io
    description: API server
security: []
paths:
  /v1/identities/dynamic/start/{session_id}:
    post:
      tags:
        - Identities
      summary: Start Dynamic Auth Flow
      description: >
        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.
      parameters:
        - name: session_id
          in: path
          required: true
          description: Active browser session that will drive the login.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthFlowV2StartRequest'
            examples:
              startLogin:
                summary: Start at a login URL
                value:
                  url: https://example.com/login
                  host: example.com
      responses:
        '200':
          description: First presentation of the auth flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthFlowV2View'
              examples:
                decision:
                  summary: Decision — choose one of several sign-in methods
                  value:
                    type: decision
                    session_id: abc-123
                    host: example.com
                    current_step_label: Sign in
                    step_id: root/login
                    options:
                      - step_id: root/login/password
                        label: Email and password
                        automatable: true
                      - step_id: root/login/google
                        label: Continue with Google
                        automatable: false
                      - step_id: root/login/sso
                        label: Continue with SSO
                        automatable: false
                form:
                  summary: Form — choose an option, then submit its values
                  value:
                    type: form
                    session_id: abc-123
                    host: example.com
                    current_step_label: Sign in
                    step_id: root/credentials
                    options:
                      - type: credentials
                        automatable: true
                        inputs:
                          - name: username
                            type: text
                            label: Email
                          - name: password
                            type: password
                            label: Password
                      - type: gmail_one_click_integration
                        automatable: true
                        inputs:
                          - name: gmail_tokens
                            type: text
                            label: Gmail token
        '400':
          description: Invalid request or host does not match url hostname
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found or not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            Auth flow transition already in progress, or navigation/discovery
            failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to start auth flow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api_key_header: []
components:
  schemas:
    AuthFlowV2StartRequest:
      type: object
      required:
        - url
        - host
      properties:
        url:
          type: string
          format: uri
          description: Landing URL to open in the session (login page).
          example: https://example.com/login
        host:
          type: string
          description: Hostname of `url`. Must match the URL hostname after normalization.
          example: example.com
    AuthFlowV2View:
      description: >
        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`.
      oneOf:
        - $ref: '#/components/schemas/AuthFlowV2DecisionView'
        - $ref: '#/components/schemas/AuthFlowV2FormView'
        - $ref: '#/components/schemas/AuthFlowV2DetectionFailedView'
        - $ref: '#/components/schemas/AuthFlowV2AuthenticatedView'
        - $ref: '#/components/schemas/AuthFlowV2FailedView'
      discriminator:
        propertyName: type
        mapping:
          decision:
            $ref: '#/components/schemas/AuthFlowV2DecisionView'
          form:
            $ref: '#/components/schemas/AuthFlowV2FormView'
          detection_failed:
            $ref: '#/components/schemas/AuthFlowV2DetectionFailedView'
          authenticated:
            $ref: '#/components/schemas/AuthFlowV2AuthenticatedView'
          failed:
            $ref: '#/components/schemas/AuthFlowV2FailedView'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    AuthFlowV2DecisionView:
      title: decision
      allOf:
        - $ref: '#/components/schemas/AuthFlowV2ViewBase'
        - type: object
          required:
            - type
            - options
          properties:
            type:
              type: string
              enum:
                - decision
            options:
              type: array
              description: |
                Each item is `{ step_id, label, automatable }`.
                POST `/resolve` with `{ "choice": "<step_id>" }`.
              items:
                $ref: '#/components/schemas/AuthFlowV2DecisionOption'
    AuthFlowV2FormView:
      title: form
      allOf:
        - $ref: '#/components/schemas/AuthFlowV2ViewBase'
        - type: object
          required:
            - type
            - options
          properties:
            type:
              type: string
              enum:
                - form
            options:
              type: array
              description: |
                Each item includes `type` and `automatable`.
                POST `/resolve` with `{ "option_index": n, "values": { ... } }`.
              items:
                $ref: '#/components/schemas/AuthFlowV2FormOption'
            credentials_rejected:
              type: boolean
              description: >-
                The last submission was rejected (e.g. wrong password) and the
                same form is re-presented.
            credentials_passed:
              type: boolean
              description: The previous step just cleared. Transient.
    AuthFlowV2DetectionFailedView:
      title: detection_failed
      allOf:
        - $ref: '#/components/schemas/AuthFlowV2ViewBase'
        - type: object
          required:
            - type
            - node_status
            - retryable
            - message
          properties:
            type:
              type: string
              enum:
                - detection_failed
            node_status:
              type: string
              enum:
                - detected
                - failed
                - explored
              description: How far the current step has been analyzed.
            last_error:
              type: string
              description: The most recent navigation error, if any.
            retryable:
              type: boolean
              description: >-
                True means keep polling `/state`; false means stop and use
                `live_view_url`.
            message:
              type: string
              description: >
                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:
      title: authenticated
      allOf:
        - $ref: '#/components/schemas/AuthFlowV2ViewBase'
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - authenticated
            message:
              type: string
              description: Human-readable status. POST `/finalize` to persist the identity.
    AuthFlowV2FailedView:
      title: failed
      allOf:
        - $ref: '#/components/schemas/AuthFlowV2ViewBase'
        - type: object
          required:
            - type
            - error
            - retryable
          properties:
            type:
              type: string
              enum:
                - failed
            error:
              type: string
              description: What went wrong.
            retryable:
              type: boolean
              description: True means keep polling `/state`; false means stop.
    AuthFlowV2ViewBase:
      type: object
      required:
        - session_id
        - host
        - current_step_label
        - step_id
        - cdp_url
        - live_view_url
      properties:
        session_id:
          type: string
        host:
          type: string
          description: Hostname the flow was started for.
        current_step_label:
          type: string
          description: Human-readable label of the current login step.
        step_id:
          type: string
          description: Identifier of the current login step.
        cdp_url:
          type: string
          description: CDP websocket URL of the session driving the login.
        live_view_url:
          type: string
          description: URL to watch or take over the session in a browser.
        discovery_error:
          type: string
          description: >-
            Set when automatic step detection hit an error. A partial flow may
            still be presented.
    AuthFlowV2DecisionOption:
      type: object
      required:
        - step_id
        - label
        - automatable
      description: |
        One option on a `decision` step. The option's `step_id` is the value to
        send as `choice` on `/resolve`; the decision view's `step_id` identifies
        the step that is asking you to choose.
      properties:
        step_id:
          type: string
          description: Opaque identifier for this option; pass it back as `choice`.
        label:
          type: string
          description: Human-readable name of the login path (e.g. "Continue with Google").
        automatable:
          type: boolean
          description: >-
            True if this path is known to be replayable unattended, without a
            human.
    AuthFlowV2FormOption:
      type: object
      required:
        - type
        - automatable
      description: >
        One way to complete a `form` step. Pick it with `option_index` on
        `/resolve`.

        `automatable` is true when this option can be replayed unattended
        (typically

        `credentials`, `totp_secret`, `gmail_one_click_integration`). Captcha,
        passkey,

        consent, and magic_link are typically false.


        `gmail_one_click_integration`: open `extra_data.create_integration_url`
        in a

        browser once; it returns a value to send as `values.gmail_tokens` on
        `/resolve`.

        The token is bound to the Gmail account, not to this flow — reuse it on
        any

        later email MFA form for that account, across applications, without

        authorizing again.
      properties:
        type:
          type: string
          enum:
            - credentials
            - mfa_totp
            - mfa_sms
            - mfa_email
            - sso
            - captcha
            - consent
            - magic_link
            - passkey
            - generic
            - totp_secret
            - gmail_one_click_integration
        automatable:
          type: boolean
          description: True if this option can be replayed unattended without a human.
        inputs:
          type: array
          items:
            type: object
            required:
              - name
              - type
            properties:
              name:
                type: string
              type:
                type: string
              label:
                type: string
              placeholder:
                type: string
              value:
                type: string
        extra_data:
          type: object
          additionalProperties: true
          description: Type-specific extras. Present only when the option has any.
          properties:
            create_integration_url:
              type: string
              format: uri
              description: >-
                On `gmail_one_click_integration`. Browser URL to connect Gmail;
                see the option description for the token it returns.
            number:
              type: string
              description: >-
                On `consent`. Device confirmation number from the live page,
                when shown.
        message:
          type: string
        provider:
          type: string
        phoneHint:
          type: string
  securitySchemes:
    api_key_header:
      type: apiKey
      in: header
      name: anchor-api-key
      description: API key passed in the header

````