---
title: "Connect a supervised session to a Poppy site (poppy_connect)"
method: POST
path: "/v1/browser/session/{session_id}/poppy"
---

# Connect a supervised session to a Poppy site (poppy_connect)

`POST /v1/browser/session/{session_id}/poppy`

## Request

- Base URL: `https://api.roveapi.com`
- URL: `https://api.roveapi.com/v1/browser/session/{session_id}/poppy`
- Auth: HTTP bearer

## Request body

- object
  - `origin` string, required: The site, an https URL.
  - `return_to` string: An https URL on the site to land on after the join.
  - `page_id` string
  - `scopes` string[]: With a stored approval: the scopes to use; [] connects signed out.
  - `replace_company_cookies` boolean: Remove the profile's existing cookies and saved data for the site first (ask the person).

## Response `200`

Successful response

- object
  - `poppy_session_id` string, required
  - `company` object, required
    - `name` string, required
    - `domain` string, required
  - `state` 'guest_joined' | 'signing_in' | 'joined' | 'expired' | 'closed' | 'failed' | 'guest' | 'signed_in' | 'revoked', required
  - `recovery` object, nullable, required
    - `toward` 'guest_joined' | 'joined', required
    - `after` 'sign_in_ended' | 'sign_in_approved' | 'revocation', required
    - `since` string, required: ISO 8601 UTC instant.
  - `signed_in` boolean, required
  - `effective_authority` object, nullable, required
    - `mode` 'held' | 'guest' | 'signed_in', required
    - `scopes` string[], required
  - `cleanup` 'none' | 'pending' | 'done' | 'failed', required
  - `last_reset` object, nullable, required
    - `at` string, required: ISO 8601 UTC instant.
    - `pages_reset` string[], required
    - `pages_closed` string[], required
  - `requested_scopes` string[], required
  - `granted_scopes` string[], required
  - `available_scopes` object[], required
    - `scope` string, required
    - `description` string, required
  - `sign_in_modes` string[], required
  - `sign_in_modes_unsupported` string[], required
  - `stored_sign_in` object, required
    - `available` boolean, required
    - `used` boolean, required
    - `scopes` string[], required
    - `signed_in_at` string: ISO 8601 UTC instant.
    - `reason` 'scopes_not_covered' | 'not_requested' | 'company_no_longer_offers'
  - `sign_in_starting` boolean, required
  - `sign_in` union, required
    - object: A sign-in that reached S5: it has the page S3 created and the deadline S5 installed.
      - `kind` 'started', required
      - `phase` 'awaiting_person' | 'authorizing' | 'exchanging' | 'joining' | 'ended', required
      - `origin` 'guest_joined' | 'joined', required
      - `requested_scopes` string[], required
      - `page_id` string, required
      - `expires_at` string, required: ISO 8601 UTC instant.
      - `start_stage` 'navigation'
      - `outcome` 'signed_in' | 'refused' | 'abandoned' | 'failed' | 'account_mismatch' | 'cancelled'
      - `reason` 'declined_at_start' | 'declined_at_company' | 'timed_out' | 'page_closed' | 'returned_without_signing_in' | 'callback_invalid' | 'authorization_error' | 'exchange_failed' | 'company_response_invalid' | 'token_not_dpop_bound' | 'company_refused' | 'company_session_ended' | 'join_failed' | 'window_start_failed' | 'agent_disconnected' | 'supervised_session_ended'
      - `detail` 'state_mismatch' | 'iss_mismatch' | 'wrong_page' | 'join_cookie_script_readable'
      - `granted_scopes` string[]
      - `off_site_auth` boolean
      - `window` 'open' | 'closing' | 'closed' | 'close_failed'
      - `agent_browser_data_off_site` boolean
      - `ended_at` string: ISO 8601 UTC instant.
    - object: A startup that failed at S1, S2 or S3: no page and no deadline, never borrowed from an earlier sign-in.
      - `kind` 'start_failed', required
      - `phase` 'ended', required
      - `origin` 'guest_joined' | 'joined', required
      - `requested_scopes` string[], required
      - `page_id` unknown, required
      - `expires_at` unknown, required
      - `outcome` 'failed', required
      - `reason` 'window_start_failed', required
      - `start_stage` 'context' | 'route' | 'page', required
      - `window` 'not_created' | 'closed' | 'close_failed', required
      - `off_site_auth` false, required
      - `agent_browser_data_off_site` false, required
      - `ended_at` string, required: ISO 8601 UTC instant.
  - `refusals` object[], required
    - `seq` integer, required
    - `at` string, required: ISO 8601 UTC instant.
    - `page_id` string, nullable, required
    - `kind` 'rove_scope_gate' | 'rove_authority_held' | 'company_refused', required
    - `method` string, required
    - `host` string, required
    - `required_scope` 'poppy:write'
    - `company_error` 'insufficient_scope' | 'sign_in_required'
  - `refusals_head_seq` integer, required
  - `refusals_dropped_through_seq` integer, required
  - `ended_reason` 'agent_disconnected' | 'supervised_session_ended' | 'account_mismatch' | 'company_session_ended' | 'join_failed' | 'token_not_dpop_bound' | 'company_refused' | 'company_response_invalid' | 'document_invalid' | 'company_unavailable'
  - `ended_detail` 'join_cookie_script_readable'
  - `ended_at` string: ISO 8601 UTC instant.
  - `next` string, required: What to do now, from the state and the latest sign-in outcome.
  - `company_cookies_cleared` integer
  - `company_storage_origins_cleared` integer
  - `page_id` string, nullable

## Other responses

- `400`: RFC 7807 poppy-invalid-origin, poppy-invalid-return-to or poppy-invalid-scope, with next
- `401`: RFC 7807 authentication problem
- `404`: RFC 7807 poppy-unavailable (Poppy off), poppy-not-participating, poppy-session-not-found or foreign-or-absent, with next
- `409`: RFC 7807 Poppy state problem (poppy-invalid-state, poppy-company-cookies-present, poppy-domain-overlap, poppy-sign-in-in-progress, …), with next
- `410`: RFC 7807 poppy-session-ended, with next
- `422`: RFC 7807 poppy-document-invalid or poppy-web-join-unsupported, with next
- `429`: RFC 7807 poppy-connect-rate-limited, poppy-sign-in-rate-limited or poppy-company-rate-limited (Retry-After), with next
- `502`: RFC 7807 poppy-company-unavailable, poppy-company-refused or poppy-join-failed (with cleanup), with next
- `503`: RFC 7807 poppy-sign-in-window-failed (with stage), with next

---

[API](https://skmtc.dev/roveapi/apis/rove-api.md) · [All operations](https://skmtc.dev/roveapi/apis/rove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roveapi/apis/rove-api/revisions/0e5d69bde586?raw)