Start OAuth connection flow

Initiates OAuth authorization flow (OAuth2 or OAuth1 depending on provider). Returns authUrl to redirect the user. If profileId is provided, it must belong to the authenticated actor (returns 403 otherwise).

POST/api/connections/connect/{scope}/{name}

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Path Parameters

scope*string

Provider scope (e.g. @appstrate)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Provider name (e.g. gmail)

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

Request Body

application/json

scopes?array<string>

profileId?string

Connection profile ID

curl -X POST "https://loading/api/connections/connect/string/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "authUrl": "string",
  "state": "string"
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "requestId": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "requestId": "req_abc123"
}