---
title: "Start an OAuth connect flow"
method: POST
path: "/v1/integrations/connect-session"
tags: ["integrations"]
---

# Start an OAuth connect flow

`POST /v1/integrations/connect-session`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/integrations/connect-session`
- Auth: HTTP bearer

Returns a provider connect URL/token the dashboard opens to authorize an app.

## Headers

- `X-Tenant-Id` string, nullable

## Request body

- ConnectSessionBody
  - `app_slug` string, required
  - `visibility` 'team' | 'personal': Who, within a tenant, may use a connected account's tools. ``TEAM``: any actor in the tenant. ``PERSONAL``: only the actor who connected it. Designed to extend to a ``GROUP`` scope later (the Groups model is already on main).
  - `environment` 'sandbox' | 'production', nullable

## Response `200`

Successful Response

- ConnectSessionResponse
  - `provider` string, required
  - `app_slug` string, required
  - `connect_url` string, nullable
  - `connect_token` string, nullable
  - `flow` string
  - `attempt_id` string, uuid, nullable

## Other responses

- `409`: Conflict: a connect for this app is already in flight and cannot be reused yet, so this ask is refused rather than served. Always TEMPORARY — the in-flight request finishes or ages out and the next ask succeeds, which is why the client should say "wait a moment" and never "refresh and retry". Inspect ``errors[0].type`` for the case: ``connect_route_changed`` (the app now routes to a different provider than the live request was minted against), ``connect_completing`` (a completion is vaulting a credential), ``connect_compensating`` (a failed attempt is being cleaned up), ``connect_environment_mismatch`` (the live request was minted for a different vendor environment than this one asks for), or ``connect_not_reusable`` (any other non-reusable live state)
- `422`: Validation Error

---

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