Connectors

Connector endpoints manage filesystem (S3, GCS, Dropbox, Google Drive) and database (PostgreSQL, BigQuery, Snowflake, etc.) connections. Credentials are encrypted at rest. Some connectors support OAuth flows.

Permissions: List, retrieve, and create operations use IsOwnerOrSharedUserOrSharedToOrg. Update and delete operations use IsOwner.

Connector Discovery

List Supported Connectors

GET/api/v1/unstract/{org_id}/supported_connectors/

Returns the list of all connector types available in the platform.▾

Get Connector Schema

GET/api/v1/unstract/{org_id}/connector_schema/

Returns the JSON Schema and OAuth information for a specific connector type.▾

Test Connector

POST/api/v1/unstract/{org_id}/test_connectors/

Tests whether the provided credentials can successfully connect to the target system. Returns 400 for invalid connectors, 403 for access denied, 408 for OAuth timeout, and 500 for test errors.▾

Connector Instances

List Connectors

GET/api/v1/unstract/{org_id}/connector/

Returns all connector instances the current user has access to.▾

Create Connector

POST/api/v1/unstract/{org_id}/connector/

Creates a new connector instance. For OAuth connectors, credentials are retrieved from Redis cache via the oauth-key query parameter. The cache entry is deleted after successful creation. Returns 408 for OAuth timeout and 409 for duplicate connector names.▾

Retrieve Connector

GET/api/v1/unstract/{org_id}/connector/{id}/

Returns the full details of a specific connector instance.▾

Update Connector (Full)

PUT/api/v1/unstract/{org_id}/connector/{id}/

Replaces all fields of a connector instance. Requires IsOwner permission. Use the oauth-key query parameter to refresh OAuth credentials.▾

Partial Update Connector

PATCH/api/v1/unstract/{org_id}/connector/{id}/

Updates specific fields of a connector instance. Requires IsOwner permission. When shared_users is updated, notifications are sent to newly added users.▾

Delete Connector

DELETE/api/v1/unstract/{org_id}/connector/{id}/

Deletes a connector instance. Requires IsOwner permission. Returns 204 on success. Returns 409 if the connector is currently in use by one or more workflows.▾

OAuth Flow

For connectors that support OAuth (e.g., Google Drive), credentials are obtained through a browser-based authorization flow.

Get OAuth Cache Key

GET/api/v1/oauth/cache-key/{backend}

Generates a cache key used to associate the OAuth flow with a connector create or update operation.▾

OAuth Flow Steps

OAuth Integration Flow

1. Get a cache key -- Call GET /oauth/cache-key/{backend} to obtain a cache_key.
2. Initiate OAuth -- Redirect the user to GET /oauth/login/{backend}/. This redirects to the OAuth provider's consent screen.
3. Provider callback -- After the user authorizes, the provider redirects to /oauth/complete/{backend}/, which caches the credentials in Redis.
4. Create or update the connector -- Pass the cache key as the ?oauth-key={cache_key} query parameter when calling the create or update endpoint.
5. Credential retrieval -- The backend retrieves the cached credentials from Redis and stores them encrypted with the connector instance.
6. Token refresh -- Token refresh is handled automatically by the platform. No manual intervention is required.

Connector Modes

Value	Description
FILE_SYSTEM	Filesystem connector (S3, GCS, Google Drive, Dropbox, etc.)
DATABASE	Database connector (PostgreSQL, BigQuery, Snowflake, etc.)