Use Connect Cards with Connector SDK

Connect Cards are embeddable pop-up windows that collect credentials directly from your end users to set up Fivetran connectors. This tutorial explains how to use Connect Cards with Connector SDK connections so that your end users can provide their own credentials without sharing them with you.

This tutorial is for you if you use Powered by Fivetran and want to embed Connector SDK-based connectors in your product and delegate credential collection to your end users.

Prerequisites

A Fivetran account with Powered by Fivetran access
A Fivetran API key
A Fivetran destination for the connection to sync data to

Overview

The setup involves two distinct phases: a one-time setup where you build your connector's packaged code and store it somewhere accessible to your backend, and a per-user onboarding flow where your backend programmatically uploads the stored code package, creates a connection with the credential keys your connector expects, and generates a Connect Card URI to send to the user.

Part 1: One-time setup

Build and store your connector package

Build a ZIP package of your connector code using the fivetran package command:

fivetran package

This produces a packaged code file. Store this file somewhere your backend can retrieve it during user onboarding, such as cloud storage (Amazon S3, Google Cloud Storage, Azure Blob Storage) or a build artifact in your CI/CD pipeline.

When you update your connector code, you can either rebuild the packaged code fresh in your CI/CD pipeline for each deployment or replace the stored version. New connections created after the update use the latest code.

Part 2: Per-user onboarding flow

Run the following steps in your backend for each new end user.

Upload connector package

Retrieve your stored packaged code and upload it using the Create Connector SDK Package endpoint. This creates a new package instance for this user's connection.

POST https://api.fivetran.com/v1/connector-sdk/packages

Upload the ZIP file as a multipart form request. The response returns a package_id:

{
    "code": "Success",
    "message": "Package created successfully",
    "data": {
        "id": "<package_id>",
        "connection_id": null,
        "created_by": "<user_id>",
        "last_updated_by": "<user_id>",
        "created_at": "2026-04-27T03:27:18.805094Z",
        "updated_at": "2026-04-27T03:27:19.010365Z",
        "file_sha256_hash": "<sha256_hash>"
    }
}

Each package can only be associated with one connection at a time. Your backend uploads the same packaged code once per end user, producing a separate package_id for each connection.

Create connection with empty secrets and Connect Card configuration

Create a connection using the Create a Connection endpoint. In the secrets_list, include the keys your connector expects at runtime but leave the values empty — your end user will fill them in through the Connect Card.

Request

POST https://api.fivetran.com/v1/connections

{
    "service": "connector_sdk",
    "group_id": "<your_group_id>",
    "run_setup_tests": false,
    "config": {
        "schema": "<connection_schema_name>",
        "package_id": "<package_id>",
        "secrets_list": [
            { "key": "API_KEY", "value": "" },
            { "key": "API_SECRET", "value": "" }
        ],
        "python_version": "3.13"
    },
    "connect_card_config": {
        "redirect_uri": "https://your-app.com/callback"
    }
}

Payload parameters

Name	Description
`service`	Must be `connector_sdk`.
`group_id`	The unique identifier for the destination group.
`run_setup_tests`	Must be set to `false`. Setup tests cannot run until the end user has provided their credentials.
`config.schema`	The destination schema name for this connection.
`config.package_id`	The package ID returned in the previous step.
`config.secrets_list`	The credential keys your connector requires. Set each `value` to an empty string — end users will provide the actual values through the Connect Card form.
`config.python_version`	Optional. The Python version to use at runtime. See Python version support for supported versions.
`connect_card_config.redirect_uri`	The URI on your site where we redirect the end user after successful setup. Must start with `https` or `http`.

Response

HTTP 201 Created

{
    "code": "Success",
    "message": "Connection has been created",
    "data": {
        "id": "<connection_id>",
        "service": "connector_sdk",
        "status": {
            "setup_state": "incomplete"
        },
        "connect_card": {
            "token": "<jwt_token>",
            "uri": "https://fivetran.com/connect-card/setup?redirect_uri=https://your-app.com/callback&auth=<jwt_token>"
        },
        "connect_card_config": {
            "redirect_uri": "https://your-app.com/callback"
        }
    }
}

Name	Description
`connect_card.token`	The Connect Card auth token.
`connect_card.uri`	The Connect Card URI to send to your end user. Valid for one day.

Redirect your end user to Connect Card URI

Send your end user to the connect_card.uri returned in the previous step.

End user fills in credentials and submits

Your end user sees a setup form where each key from secrets_list is displayed as a labeled field. They fill in the corresponding values and click Save & Test. If the setup tests pass, the end user is redirected to your redirect_uri. If the tests fail, the end user can correct their credentials and retry.

For general information about Connect Cards, including URI format, expiry, and restrictions, see the Connect Cards overview.