airbyte/docs/ai-agents/embedded/api/configuring-sources.md

products

products
embedded

Authentication & Token Management

Overview

Airbyte Embedded uses a two-tier authentication system:

1. Organization-level tokens: Your main API credentials for managing templates and connections
2. User-scoped tokens: Temporary tokens that allow end-users to configure sources in their isolated workspaces

For complete authentication documentation including widget tokens and region selection, see Authentication.

Generating user-scoped tokens

When collecting credentials from your users, generate a scoped access token that only has permissions to read and modify integrations in their specific workspace. This follows the principle of least privilege and ensures user data isolation.

This can be done by submitting a request to:

curl --location 'https://api.airbyte.ai/api/v1/embedded/scoped-token' \

  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Organization-Id: <your_organization_id>' \
  --data '{

    "workspace_name": "your_workspace_name",
    "region_id": "optional_region_id"
  }'

Where:

• workspace_name is a unique identifier within your organization for each customer's tenant
• region_id (optional) is the region where the workspace should be created:
  • US region: 645a183f-b12b-4c6e-8ad3-99e165603450 (default)
  • EU region: b9e48d61-f082-4a14-a8d0-799a907938cb

The API will return a JSON object with a token string:

{
  "token": "eyJ0b2tlbiI6ImV5SmhiR2NpT2lKSVV6STFOaUo5..."
}

Understanding the token response

The response contains a scoped JWT token that can be used to:

• Create and manage sources in the workspace
• List available source templates
• Create connections from sources

Using the scoped token

Use the token as a Bearer token in subsequent API calls:

curl https://api.airbyte.ai/api/v1/embedded/sources \

  -H 'Authorization: Bearer <scoped_token>'

For widget integration, see Authentication - Widget Token.

Creating a Source

You'll need 3 pieces of information to create a source for your users:

1. Their workspace ID
2. The ID of the Source Template used
3. The connection configuration

Basic source creation

Here is an example request:

curl --location 'https://api.airbyte.ai/api/v1/embedded/sources' \

  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <scoped_token>' \
  --header 'X-Organization-Id: <your_organization_id>' \
  --data '{

    "name": "your_source_name",
    "workspace ID": "your_workspace ID",
    "source_template_id": "your_source_template_id",
    "source_config": {
      // your source configuration fields here
    }
  }'

The connection configuration should include all required fields from the connector specification, except for the ones included as default values in your source template.

You can find the full connector specification in the Connector Registry.

You can find the reference docs for creating a source here.

Filtering connection templates with tags

When creating a source, you can control which connection templates are available by using tag filtering:

curl --location 'https://api.airbyte.ai/api/v1/embedded/sources' \

  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <scoped_token>' \
  --header 'X-Organization-Id: <your_organization_id>' \
  --data '{

    "name": "your_source_name",
    "workspace ID": "your_workspace ID",
    "source_template_id": "your_source_template_id",
    "source_config": {},
    "selected_connection_template_tags": ["analytics", "standard-sync"],
    "selected_connection_template_tags_mode": "any"
  }'

Tag Selection Modes:

• any - Connection template must have at least one of the specified tags
• all - Connection template must have all of the specified tags

This allows you to customize which sync configurations are available based on customer tier, compliance requirements, or other criteria. See Template Tags for more information.

Controlling which streams are synced

Stream selection is configured at the source template level using the customization field. This allows you to control which streams from a connector are included when connections are created from that template.

Stream selection modes

There are three stream selection modes available:

• suggested (default) - Only sync streams marked as "suggested" by the connector. If no streams are marked as suggested, all streams are synced.
• all - Sync all available streams from the source
• whitelist - Only sync specific streams that you explicitly list

Whitelisting specific streams

To whitelist specific streams, configure your source template with the whitelist mode and provide a list of stream names:

curl --location 'https://api.airbyte.ai/api/v1/embedded/templates/sources' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Organization-Id: <your_organization_id>' \
  --data '{
    "name": "PostgreSQL Analytics Template",
    "actor_definition_id": "decd338e-5647-4c0b-adf4-da0e75f5a750",
    "partial_default_config": {
      "ssl_mode": {"mode": "require"}
    },
    "customization": {
      "stream_selection_mode": "whitelist",
      "stream_whitelist": ["orders", "customers", "products"]
    }
  }'

Important notes:

• Syncing all streams can cause perceived performance issues depending on the source
• When using whitelist mode, you must provide a non-empty stream_whitelist array
• Stream names must exactly match the stream names provided by the connector
• When a source is created from this template, only the whitelisted streams will be available for syncing
• To find available stream names for a connector, use the discover endpoint

For more information about creating and configuring source templates, see Source Templates.

Related documentation

• Source Templates - Create and manage source templates
• Connection Templates - Configure sync behavior
• Template Tags - Organize templates with tags
• Authentication - Token generation and management