Platform Setup (Airbyte Cloud / Hosted Mode)

Platform Setup (Airbyte Cloud / Hosted Mode)

This guide covers setting up connectors through the Airbyte Platform (app.airbyte.ai), where connectors appear in your dashboard and credentials are managed securely.

Contents

• When to Use Platform Mode
• Prerequisites
• Creating Connectors with create_hosted()
• Using Existing Connectors
• OAuth Connectors (Salesforce, HubSpot, Google Drive, etc.)
• Making Connectors Visible in the UI
• Creating Connector Instances
• Verifying Connector in UI
• Entity Cache
• Environment Variables Setup
• Troubleshooting Platform Setup
• Complete Setup Checklist
• Related Documentation

When to Use Platform Mode

Use Platform Mode when you want:

• Connectors visible in the Airbyte UI
• Managed credential storage and rotation
• Entity cache for faster repeated queries
• Multi-tenant SaaS deployments
• OAuth flows handled server-side

Prerequisites

Get Your Airbyte Platform Credentials

1. Sign up at app.airbyte.ai
2. Go to Settings > API Keys
3. Create a new API key to get:
   • AIRBYTE_CLIENT_ID
   • AIRBYTE_CLIENT_SECRET

These are your application-level credentials for creating and managing connectors programmatically.

Define Your External User ID

The external_user_id is YOUR identifier for the user or tenant - you define it:

• "user_123" - for user-scoped connectors
• "acme-corp" - for organization-scoped connectors
• "tenant_abc" - for multi-tenant applications

This ID is used to:

• Scope connectors to specific users/tenants
• Look up existing connectors without storing connector IDs

Creating Connectors with create_hosted()

API Key Connectors

For connectors using API keys (Stripe, Gong, Jira, etc.):

import os
from airbyte_agent_stripe import StripeConnector
from airbyte_agent_stripe.models import StripeAuthConfig

# Create and register a new connector
connector = await StripeConnector.create_hosted(
    external_user_id="user_123",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
    auth_config=StripeAuthConfig(api_key=os.environ["STRIPE_API_KEY"]),
    name="Stripe Source"  # Optional: display name in UI
)

# Connector is created and ready to use programmatically
# For UI visibility, register a template (see "Making Connectors Visible in the UI" below)

# Use it immediately
result = await connector.execute("customers", "list", {"limit": 10})

Gong Example

from airbyte_agent_gong import GongConnector
from airbyte_agent_gong.models import GongAccessKeyAuthenticationAuthConfig

connector = await GongConnector.create_hosted(
    external_user_id="acme-corp",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
    auth_config=GongAccessKeyAuthenticationAuthConfig(
        access_key=os.environ["GONG_ACCESS_KEY"],
        access_key_secret=os.environ["GONG_ACCESS_KEY_SECRET"]
    ),
    name="Gong Source"
)

GitHub with Personal Access Token

from airbyte_agent_github import GithubConnector
from airbyte_agent_github.models import GithubPersonalAccessTokenAuthConfig

connector = await GithubConnector.create_hosted(
    external_user_id="user_123",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
    auth_config=GithubPersonalAccessTokenAuthConfig(
        token=os.environ["GITHUB_TOKEN"]
    ),
    name="GitHub Source"
)

Using Existing Connectors

Once a connector is created, you don't need to pass auth_config again:

# Option A: Look up by external_user_id
connector = StripeConnector(
    external_user_id="user_123",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
)

# Option B: Use connector_id directly (if you have it cached)
connector = StripeConnector(
    connector_id="your-connector-uuid",  # From previous create_hosted() or API
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
)

# Operations use credentials stored in Airbyte
result = await connector.execute("customers", "list", {"limit": 10})

OAuth Connectors (Salesforce, HubSpot, Google Drive, etc.)

OAuth connectors require a server-side flow to capture user authorization.

Step 1: Initiate OAuth

from airbyte_agent_salesforce import SalesforceConnector

# Start the OAuth flow
oauth_response = await SalesforceConnector.initiate_oauth(
    external_user_id="user_123",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
    redirect_url="https://yourapp.com/oauth/callback"
)

# Redirect user to the consent URL
print(f"Redirect user to: {oauth_response.consent_url}")

Step 2: Handle OAuth Callback

When the user completes authorization, they're redirected to your callback URL with a secret_id parameter:

https://yourapp.com/oauth/callback?secret_id=abc123

Step 3: Create Connector with OAuth Secret

connector = await SalesforceConnector.create_hosted(
    external_user_id="user_123",
    airbyte_client_id=os.environ["AIRBYTE_CLIENT_ID"],
    airbyte_client_secret=os.environ["AIRBYTE_CLIENT_SECRET"],
    server_side_oauth_secret_id="abc123",  # From callback
    name="Salesforce Source"
)

OAuth Connectors Reference

Making Connectors Visible in the UI

After create_hosted() succeeds, the connector is functional programmatically. To make it appear in the Airbyte UI's Connectors page, you must register it as a template.

Register a UI 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

Get the 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>"
  }'

Use the access_token from the response as <APPLICATION_TOKEN>.

Example: Register Gong Connector

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"
  }'

After registration, your connector appears in the Connectors page with a card showing the name and "Direct" badge.

Creating Connector Instances

After registering a template, you need to create an actual connector instance to access data.

Note: create_hosted() has a known URL bug. Use the HTTP API above until the SDK is updated.

Step 1: List Workspaces

First, find your workspace name:

curl 'https://api.airbyte.ai/api/v1/workspaces' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>'

Use the workspace name (not id) as your external_user_id when creating connectors.

Step 2: Create Instance

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_user_id": "<YOUR_WORKSPACE_NAME>",
    "workspace_name": "<YOUR_WORKSPACE_NAME>",
    "definition_id": "<DEFINITION_ID>",
    "name": "my-connector",
    "credentials": {
      // Connector-specific fields ONLY - no auth_type or credentials_title
    }
  }'

Credentials Format by Connector

Do NOT include discriminator fields like auth_type or credentials_title — the API infers auth type from the credentials structure and rejects these.

Step 3: Verify Connection

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

A successful response confirms your connector is working.

Verifying Connector in UI

After registering the template:

1. Go to app.airbyte.ai
2. Navigate to Connectors page
3. Your connector should appear with the name you specified and a "Direct" badge
4. Click to view status, configuration, and usage

Entity Cache

Platform connectors support entity caching for faster repeated queries. Entity cache is managed through the Airbyte UI:

1. Go to app.airbyte.ai
2. Select your connector
3. Enable entity cache in the connector settings

When entity cache is enabled:

• Common queries are cached and served faster
• Cache syncs automatically in the background
• View cache status in the Airbyte UI

Environment Variables Setup

Create a .env file for your platform credentials:

# Airbyte Platform (from app.airbyte.ai > Settings > API Keys)
AIRBYTE_CLIENT_ID=your_client_id
AIRBYTE_CLIENT_SECRET=your_client_secret

# Connector credentials (varies by connector)
STRIPE_API_KEY=sk_live_...
GONG_ACCESS_KEY=...
GONG_ACCESS_KEY_SECRET=...
GITHUB_TOKEN=ghp_...

Load in Python:

from dotenv import load_dotenv
import os

load_dotenv()

# Now use os.environ to access credentials

Troubleshooting Platform Setup

"Invalid client credentials"

• Verify AIRBYTE_CLIENT_ID and AIRBYTE_CLIENT_SECRET are correct
• Regenerate API keys in app.airbyte.ai > Settings > API Keys

"Connector not appearing in UI"

• Ensure create_hosted() completed without errors
• Check the external_user_id matches your workspace
• Refresh the UI page

"OAuth flow failing"

• Verify redirect URL matches exactly
• Check OAuth app settings in the third-party service
• Ensure required scopes are configured

"create_hosted() not found"

• Update your SDK: pip install --upgrade airbyte-agent-{connector}
• create_hosted() was added in SDK v0.1.0

Complete Setup Checklist

Follow these steps IN ORDER. Do not skip ahead.

Prerequisites

• Airbyte Cloud account at app.airbyte.ai
• Connector credentials (API key, OAuth app, etc.)

Step 1: Get Application Token (REQUIRED)

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

Save the access_token as APPLICATION_TOKEN.

Token TTL: Tokens expire after 15 minutes. Re-run this step if you get unauthorized errors later.

Step 2: Detect Workspace

curl 'https://api.airbyte.ai/api/v1/workspaces' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>'

• If ONE workspace: use it automatically
• If MULTIPLE: ask user which workspace to use

Step 3: Check if Template Exists (CRITICAL)

curl 'https://api.airbyte.ai/api/v1/integrations/templates/sources' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>'

Look for an existing template for your connector.

• If template EXISTS: skip to Step 5
• If NO template: proceed to Step 4

Step 4: Register Template (Required if none exists)

You need the Definition ID for your connector:

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": "<DEFINITION_ID>",
    "name": "<CONNECTOR_NAME>",
    "original_source_template_id": "",
    "partial_default_config": {},
    "mode": "DIRECT"
  }'

Use "mode": "DIRECT" for all connectors. If the API rejects the mode, check the error for accepted values.

Idempotency Note: If you get "already exists" error, a template with that name already exists. Either:

• Use a different name, OR
• Skip this step and use the existing template

Step 5: Create Connector Instance

curl -X POST 'https://api.airbyte.ai/api/v1/integrations/connectors' \
  -H 'Authorization: Bearer <APPLICATION_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_user_id": "<WORKSPACE_NAME>",
    "workspace_name": "<WORKSPACE_NAME>",
    "definition_id": "<DEFINITION_ID>",
    "name": "my-connector",
    "credentials": {
      "api_key": "..."
    }
  }'

• external_user_id: Your identifier for this user/tenant (use workspace name for simplicity)
• definition_id: The connector definition ID from the table in Step 4
• Note: Do NOT include discriminator fields like auth_type or credentials_title in credentials — the API infers auth type and rejects these.

Note: create_hosted() has a known URL bug. Use the HTTP API above until the SDK is updated.

Step 6: Verify with Test Query

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

Step 7: Create .env File

Create .env in the connector directory:

AIRBYTE_CLIENT_ID=...
AIRBYTE_CLIENT_SECRET=...
# Connector-specific credentials
API_KEY=...

Confirm: "Connector created and verified! Pulled [N] records successfully."

Related Documentation

• OSS Setup - Local SDK without platform integration
• Authentication - Auth patterns by connector
• Programmatic Setup - HTTP API and curl examples
• Troubleshooting - Common errors and solutions
• Entity-Action API - Core API patterns