Connect

Create connections via the hosted connect flow for OAuth2 and all other authentication types.

Connect

The Connect endpoints provide a hosted connect flow for creating connections across all authentication types (OAuth2, API keys, custom auth). Weavz hosts the entire authorization process — you create a session token, open the connect page, and retrieve the result.

Hosted Connect Flow

POST/api/v1/connect/token

Create a connect session token. Returns a token and a connectUrl that you open in a popup or redirect to start the authorization flow.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration to connect (e.g., `slack`, `google-sheets`)
`connectionName`	string	Yes	Display name for the resulting connection
`externalId`	string	Yes	Customer-defined connection `externalId` selector
`workspaceId`	string (uuid)	Yes	Workspace to create the connection in
`workspaceIntegrationId`	string (uuid)	No	Configured workspace integration to connect. When provided, hosted connect inherits its `authMethodKey` and OAuth app policy.
`authMethodKey`	string	Conditional	Auth method key to use when connecting by `integrationName`. Required when multiple auth options exist and no `workspaceIntegrationId` is provided.
`endUserId`	string	No	The end user's `externalId` to associate the connection with
`scope`	string	No	Connection scope: `ORGANIZATION`, `WORKSPACE`, or `USER`. Defaults to `ORGANIZATION`
`oauthAppMode`	string	No	OAuth app policy for OAuth auth methods: `weavz_managed` or `custom`. Defaults to `weavz_managed`.
`oauthAppId`	string (uuid)	Conditional	Tenant-owned custom OAuth app UUID. Required when `oauthAppMode` is `custom`; omit for Weavz-managed OAuth.
`successRedirectUri`	string (url)	No	URL to redirect to after a successful hosted connect flow
`errorRedirectUri`	string (url)	No	URL to redirect to after a failed hosted connect flow

Response

json

{
  "token": "cst_550e8400-e29b-41d4-a716-446655440000",
  "connectUrl": "https://platform.weavz.io/connect?token=cst_550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2025-01-15T14:30:00.000Z"
}

Connect session tokens expire after 4 hours. Use the returned expiresAt to decide when your frontend should stop polling or ask your backend for a fresh token.

Example

bash

curl -X POST https://platform.weavz.io/api/v1/connect/token \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "google-sheets",
    "connectionName": "Google Sheets",
    "externalId": "conn_tenant_123_gsheets",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "successRedirectUri": "https://your-app.com/connect/success",
    "errorRedirectUri": "https://your-app.com/connect/error"
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { token, connectUrl } = await client.connect.createToken({
  integrationName: 'google-sheets',
  connectionName: 'Google Sheets',
  externalId: 'conn_tenant_123_gsheets',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  successRedirectUri: 'https://your-app.com/connect/success',
  errorRedirectUri: 'https://your-app.com/connect/error',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.connect.create_token(
    integration_name="google-sheets",
    connection_name="Google Sheets",
    external_id="conn_tenant_123_gsheets",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    success_redirect_uri="https://your-app.com/connect/success",
    error_redirect_uri="https://your-app.com/connect/error",
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/connect/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'google-sheets',
    connectionName: 'Google Sheets',
    externalId: 'conn_tenant_123_gsheets',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    successRedirectUri: 'https://your-app.com/connect/success',
    errorRedirectUri: 'https://your-app.com/connect/error',
  }),
})
const data = await res.json()

python

import httpx
 
res = httpx.post(
    "https://platform.weavz.io/api/v1/connect/token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "google-sheets",
        "connectionName": "Google Sheets",
        "externalId": "conn_tenant_123_gsheets",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "successRedirectUri": "https://your-app.com/connect/success",
        "errorRedirectUri": "https://your-app.com/connect/error",
    },
)
data = res.json()

Open the connectUrl in a popup window or redirect the user to it. The hosted page handles the full OAuth2 consent flow.

For OAuth2 integrations, Weavz selects the OAuth app when the connect token is created. By default, OAuth connect sessions use the Weavz-managed OAuth app. Team, Scale, and Enterprise organizations can register tenant-owned OAuth apps for branded consent screens, custom scopes, and provider quota isolation, then select one with oauthAppMode: "custom" and oauthAppId. oauthAppId is always a real OAuth app UUID; there is no sentinel value for Weavz-managed OAuth.

When you pass workspaceIntegrationId, hosted connect uses that configured instance's auth method and OAuth app policy. This is the preferred path for workspace integrations with multiple auth options or a custom OAuth app selected in the dashboard.

Errors

Status	Code	Description
`400`	`NO_OAUTH_APP`	No OAuth app is configured for this integration
`400`	`AUTH_METHOD_REQUIRED`	The integration has multiple auth options and `authMethodKey` was not provided
`400`	`INVALID_AUTH_METHOD`	The requested `authMethodKey` is not available for the integration
`400`	`INVALID_OAUTH_APP`	OAuth app fields were provided for a non-OAuth auth method or the custom OAuth app is invalid
`403`	`CUSTOM_OAUTH_APP_PLAN_REQUIRED`	Tenant-owned OAuth apps are not available on the current plan
`404`	`INTEGRATION_NOT_FOUND`	Integration not found
`404`	`OAUTH_APP_NOT_FOUND`	Requested OAuth app does not exist or is not available to the organization

Get Connect Session

GET/api/v1/connect/session/:sessionId

Retrieve a connect session by its Weavz session ID using your API key. Use this when your backend stored the session ID and wants an authenticated status lookup.

Path Parameters

Field	Type	Description
`sessionId`	string	Connect session ID

Response

json

{
  "session": {
    "id": "c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111",
    "integrationName": "google-sheets",
    "connectionName": "Google Sheets",
    "externalId": "conn_tenant_123_gsheets",
    "status": "COMPLETED",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "error": null,
    "expiresAt": "2025-01-15T14:30:00.000Z",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

bash

curl https://platform.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { session } = await client.connect.getSession('c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111')

python

result = client.connect.get_session("c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111")
session = result["session"]

typescript

const res = await fetch('https://platform.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.get(
    "https://platform.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`403`	`FORBIDDEN`	Session belongs to another organization
`404`	`NOT_FOUND`	Connect session not found

Poll Connect Session

POST/api/v1/connect/session/poll

Retrieve the status and result of a connect session using the short-lived cst_ token returned by POST /api/v1/connect/token. Poll this endpoint after the user completes (or closes) the connect page.

Request Body

Field	Type	Description
`token`	string	The `cst_` token returned from `POST /api/v1/connect/token`

Response

json

{
  "status": "COMPLETED",
  "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
  "integrationName": "google-sheets",
  "externalId": "conn_tenant_123_gsheets",
  "error": null
}

Session statuses:

Status	Description
`PENDING`	Connect page not yet opened or user still authorizing
`CONNECTING`	Authorization is being completed
`COMPLETED`	Authorization succeeded, `connectionId` contains the new connection
`FAILED`	Authorization failed, `error` field contains the error message

Example

bash

curl -X POST https://platform.weavz.io/api/v1/connect/session/poll \
  -H "Content-Type: application/json" \
  -d '{"token":"cst_your_connect_token"}'

typescript

const session = await client.connect.wait(token)

python

result = client.connect.wait(token)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/connect/session/poll', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }),
})
const data = await res.json()

python

res = httpx.post(
    "https://platform.weavz.io/api/v1/connect/session/poll",
    json={"token": token},
)
data = res.json()

Errors

Status	Code	Description
`400`	`MISSING_TOKEN`	Token was not provided
`401`	`INVALID_TOKEN`	Token is invalid or expired