Initiate Oauth

Initiate an OAuth authentication flow.

This endpoint generates an authorization URL that the user should visit to grant permissions to the integration.

Flow:

1. Call this endpoint with the integration ID
2. Redirect the user to the returned auth_url
3. User grants permissions on the provider’s website
4. Provider redirects back to the callback URL with a code
5. Callback handler exchanges code for tokens and creates connection

Example:

POST /oauth/initiate
{
    "integration_id": "gmail",
    "auth_method_id": "oauth2",
    "scopes": [
        "https://www.googleapis.com/auth/gmail.readonly",
        "https://www.googleapis.com/auth/gmail.send"
    ]
}

Response:

{
    "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
    "state": "abc123...",
    "integration_id": "gmail"
}

POST /api/v1/oauth/initiate

Initiate Oauth

cURL

curl --request POST \
  --url https://api.example.com/api/v1/oauth/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integration_id": "<string>",
  "auth_method_id": "oauth2",
  "scopes": [
    "<string>"
  ],
  "redirect_uri": "<string>"
}
'

422

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Workspace-Id · string | null

The workspace ID

Body

application/json

Request to initiate OAuth flow.

integration_id · string · required

auth_method_id · string · default: oauth2

scopes · string[] | null

redirect_uri · string | null

Response

200

application/json

Successful Response