Programmatic Connector Setup

Programmatic Connector Setup

Set up connectors entirely from the terminal or via HTTP APIs—no UI required.

Contents

• When to Use This Guide
• Prerequisites
• Step 1: Get Application Token
• Choose Your Pattern
• Pattern A: Scoped Token Flow
• Pattern B: Workspace Flow
• Pattern C: UI Template Registration
• Connector Definition IDs
• Token Reference
• SDK vs HTTP API vs UI Decision Guide
• Troubleshooting
• Related Documentation

When to Use This Guide

Prerequisites

You need Airbyte application credentials:

• AIRBYTE_CLIENT_ID - from app.airbyte.ai settings (one-time)
• AIRBYTE_CLIENT_SECRET - from app.airbyte.ai settings (one-time)

Step 1: Get Application Token

curl -X POST 'https://api.airbyte.ai/api/v1/account/applications/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<AIRBYTE_CLIENT_ID>",
    "client_secret": "<AIRBYTE_CLIENT_SECRET>"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1..."
}

Save this as APPLICATION_TOKEN. Use it for all subsequent requests.

Choose Your Pattern

Pattern A: Scoped Token Flow (Recommended for API Key Connectors)

Step A2: Get Scoped Token

curl -X POST 'https://api.airbyte.ai/api/v1/embedded/scoped-token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -d '{
    "workspace_name": "<EXTERNAL_USER_ID>"
  }'

The workspace_name is your identifier for the user/tenant (you define this).

Response:

{
  "access_token": "eyJhbGciOiJIUzI1..."
}

Save this as SCOPED_TOKEN.

Step A3: Create Connector

For API Key Connectors (Stripe, Gong, Jira, etc.):

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <SCOPED_TOKEN>' \
  -d '{
    "definition_id": "<CONNECTOR_DEFINITION_ID>",
    "name": "my-stripe-connector",
    "auth_config": {
      "api_key": "<YOUR_API_KEY>"
    }
  }'

Response:

{
  "id": "abc123-connector-id",
  "name": "my-stripe-connector",
  ...
}

Save the id as CONNECTOR_ID.

Step A4: Execute Operations

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors/<CONNECTOR_ID>/execute' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -d '{
    "entity": "customers",
    "action": "list",
    "params": {"limit": 10}
  }'

Pattern B: Workspace Flow (For OAuth Connectors)

Use this pattern when you need OAuth (Salesforce, HubSpot, Google Drive, Intercom, etc.).

Step B2: Create Workspace

curl -X POST 'https://api.airbyte.ai/api/v1/workspaces' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "customer_<UNIQUE_ID>"
  }'

Response:

{
  "workspaceId": "a1b2c3d4-...",
  "name": "customer_12345"
}

Save workspaceId.

Step B3: Initiate OAuth

curl -X POST 'https://api.airbyte.ai/api/v1/sources/initiateOAuth' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": "<WORKSPACE_ID>",
    "sourceType": "intercom",
    "redirectUrl": "https://your-app.com/oauth/callback"
  }'

Response:

{
  "consentUrl": "https://app.intercom.com/oauth/..."
}

Redirect user to consentUrl. After authorization, they return to your redirectUrl with a secret_id parameter.

Step B4: Create Source with OAuth Secret

curl -X POST 'https://api.airbyte.ai/api/v1/sources' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "workspaceId": "<WORKSPACE_ID>",
    "name": "intercom-connector",
    "secretId": "<SECRET_ID_FROM_CALLBACK>",
    "configuration": {
      "sourceType": "intercom",
      "start_date": "2021-01-01T00:00:00Z"
    }
  }'

Response includes sourceId.

Step B5: Execute Operations

curl -X POST 'https://api.airbyte.ai/api/v1/connectors/sources/<SOURCE_ID>/execute' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -d '{
    "entity": "contacts",
    "action": "list",
    "params": {"per_page": 50}
  }'

Pattern C: UI Template Registration

Use this pattern to make connectors appear in the Airbyte UI's Connectors page. Run this after creating a connector with Pattern A or B.

Why Register a Template?

When you create a connector programmatically via create_hosted() or the HTTP API, it's functional but not visible in the UI. Registering a template creates a card in the Connectors page at app.airbyte.ai.

Step C1: Register the Template

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/templates/sources' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -d '{
    "actor_definition_id": "<CONNECTOR_DEFINITION_ID>",
    "name": "Gong",
    "original_source_template_id": "",
    "partial_default_config": {},
    "mode": "DIRECT"
  }'

Parameters

Example: Register Gong Connector

# Using the APPLICATION_TOKEN from Step 1
curl -X POST 'https://api.airbyte.ai/api/v1/integrations/templates/sources' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1...' \
  -d '{
    "actor_definition_id": "32382e40-3b49-4b99-9c5c-4076501914e7",
    "name": "Gong",
    "original_source_template_id": "",
    "partial_default_config": {},
    "mode": "DIRECT"
  }'

Example: Register Salesforce Connector

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/templates/sources' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -d '{
    "actor_definition_id": "b117307c-14b6-41aa-9422-947e34922962",
    "name": "Salesforce",
    "original_source_template_id": "",
    "partial_default_config": {},
    "mode": "DIRECT"
  }'

Troubleshooting Template Registration

Verify in UI

After successful registration:

1. Go to app.airbyte.ai
2. Navigate to the Connectors page
3. Your connector appears as a card with the name and a "Direct" or "OAuth" badge

Connector Definition IDs

Token Reference

SDK vs HTTP API vs UI Decision Guide

Recommendation:

• Python apps: Use the SDK (create_hosted())—it handles tokens automatically
• Non-Python or scripts: Use HTTP API with this guide
• Exploration/debugging: Use the UI at app.airbyte.ai

Troubleshooting

"Invalid token" errors

• Application tokens expire; regenerate if needed
• Ensure you're using the right token type for each endpoint:
  • Application token: workspace creation, OAuth initiation
  • Scoped token: connector instance creation

"Connector not found" errors

• Verify CONNECTOR_ID from creation response
• Check you're using the correct SCOPED_TOKEN for that user

"Unauthorized" errors

• Verify your AIRBYTE_CLIENT_ID and AIRBYTE_CLIENT_SECRET
• Regenerate the application token

Related Documentation

• Authentication - SDK-based auth patterns
• Getting Started - Installation and setup
• Entity-Action API - Core API patterns