Getting Started

The Fivetran REST API allows you to programmatically manage your Fivetran account, groups, destinations, and connections, trigger syncs, and monitor status. This guide explains how to get access, send your first request, and identify which connectors support API access and their authorization methods.

REST API quickstart guide

This section covers the concepts and prerequisites for creating connections and other group-scoped resources using the API.

1. Get an API key

Before you call the API, authenticate with an API key. Use a Scoped API key. It's tied to your Fivetran user account and inherits your RBAC permissions, so you can only access resources within your permission scope.

2. Set up a group and destination

A group is the top-level container in Fivetran. The following resources all require a group to exist before you can create them:

• Destinations
• Connections
• dbt Core transformation projects
• External logging configurations
• Hybrid deployment agents

Once a destination exists for a group, group_id, destination_id, and destination_group_id all refer to the same entity across API requests. See How Do Destinations and Groups Relate? for details.

If you don't have a group and destination yet:

1. Call POST /v1/groups to create a group. Note the id in the response — this is your group_id.
2. Call POST /v1/destinations using that group_id to add a destination to the group.

If you already have a destination, call GET /v1/destinations to find its group_id.

3. Find the connector service identifier

The service field in a connection request uses an internal connector identifier — for example, github or google_sheets — that may not match the connector's display name in the Fivetran dashboard. Use GET /v1/metadata/connectors to list all available connectors and their id values. The id is the value to use in the service field.

API reference examples and required fields

The API Reference shows all applicable fields and options for each resource type — for connections, destinations, and others. These are not minimal working requests — copy-pasting an example without replacing all placeholders and removing inapplicable fields will result in errors or unexpected behavior.

To create a connection, you must provide the following fields:

• group_id — the destination group where the connection will live. See step 2 above.
• service — the connector type identifier (for example, google_sheets). See step 3 above.
• config — the connector-specific credentials and connection parameters. For the full list of config fields per connector type, see the Create a Connection reference.

A request missing any of these fields returns a 400 Bad Request error.

Common terms

Also, explore the Fivetran REST API Postman collection to try requests quickly, and review webhooks for event-driven updates.

Authentication

The Fivetran REST API uses API key authentication. If you're getting started, use a Scoped API key — it's tied to your Fivetran user account and inherits your RBAC permissions. For centralized, organization-managed key management, use a System key instead.

Base URL

All API requests use this root URL: https://api.fivetran.com/v1/

Scoped API key

A Scoped API key is a key-secret pair that you create as a Fivetran user to call the Fivetran REST API. The Scoped API key links to your account and inherits your RBAC permissions.

Instructions

1. In the Fivetran dashboard, click your username.

2. Click API Key.

3. Click Generate API key (or Generate new API key if one already exists).

4. Make a note of the key and secret as they disappear once you close the page or navigate away. You need the key and secret to access your Fivetran account using the API.

API secret regeneration

We recommend you regenerate your API secret in the following cases:

• The API secret has been exposed or lost
• You are cloning or migrating your environment
• There was a team or vendor change
• It's time for a routine rotation

To generate a new secret, do the following:

1. In the Fivetran dashboard, click your username.

2. Click API Key.

3. Click Generate new API key.

4. Click Generate new secret.

   This action instantly replaces your API secret key with a new one.

Scoped API key FAQs

Read answers to frequently asked questions about our scoped API keys.

System API key

A System key is an organization-managed API key–secret pair for the Fivetran REST API. Use System keys to replace user-oriented, scoped API keys. Instead of relying on RBAC to scope permissions, you set permission at the key level and manage them centrally. This solves for key pain points in securely managing keys, allowing you to understand usage, rotation, and other key information.

See our System Keys documentation for more details.

Use API key in requests

For each request to the API, send the Base64-encoded string api_key:api_secret in the Authorization HTTP header.

Authorization: Basic <base64(api_key:api_secret)>

You can use the -u flag for curl to encode to Base64:

curl -u api_key:api_secret "https://example.com"

Or, you can encode to Base64 by running one of the following commands in CLI (depending on your environment):

• On Linux/macOS:

  echo -n '<API Key>:<Secret Key>' | base64
  

• On Linux/macOS (using OpenSSL):

  echo -n '<API Key>:<Secret Key>' | openssl base64
  

• On Windows (Command Prompt with OpenSSL installed):

  echo "<API Key>:<Secret Key>" | openssl base64
  

• On Windows (PowerShell):

  [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("<API Key>:<Secret Key>"))
  

Example

• API key - d9c4511349dd4b86
• Secret - 1f6f2d161365888a1943160ccdb8d968
• Concatenated string - d9c4511349dd4b86:1f6f2d161365888a1943160ccdb8d968
• Base64-encoded string - ZDljNDUxMTM0OWRkNGI4NjoxZjZmMmQxNjEzNjU4ODhhMTk0MzE2MGNjZGI4ZDk2OA==

Authorization HTTP header: Authorization: Basic ZDljNDUxMTM0OWRkNGI4NjoxZjZmMmQxNjEzNjU4ODhhMTk0MzE2MGNjZGI4ZDk2OA==

Request content type

The Fivetran Public API only accepts requests with the Content-Type: application/json header explicitly specified in them. Make sure this header is present on your POST and PATCH calls.

Example request

curl -X POST "https://api.fivetran.com/v1/groups" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u "api_key:api_secret" \
  -d '{"name":"Group_Name"}'

Response

Every response has the following format:

{
  "code": "Success",
  "message": "message",
  "data": {}
}

Example response

{
  "code": "Success",
  "message": "Group has been created",
  "data": {
    "id": "group_id",
    "name": "Group_Name",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Fields

Error codes

We respond with standard codes for errors that occur during request processing.

Authorization methods for connectors

Authorization gives a connector permission to read from the source system (for example, Instagram, Salesforce, DB). Until you authorize the connector, it can’t fetch data even though you have successfully authenticated to the API.

You can authorize some connectors entirely by API, while others require a Connect Card flow. Support varies by connector.

• Connect Card - Redirect end users to an embeddable setup flow so they can authorize without sharing credentials with you. Use Connect Cards if you’re implementing a Powered by Fivetran workflow, or whenever obtaining end user credentials is difficult.

• API-based authorization - Provide credentials in the connection payload using one of these methods:

  • Define an auth section in the request body.
  • Provide the login and password fields.
  • Provide a token and any related fields.
  • Provide a key and any related fields.

  Use API-based authorization when you control the source credentials and want a fully automated setup (for example, in automated pipelines, Infrastructure as Code (IaC), or bulk provisioning of connections).

  Token-based auth example

  curl -X POST "https://api.fivetran.com/v1/connectors" \
  -u "$FIVETRAN_API_KEY:$FIVETRAN_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "YOUR_GROUP_ID",
    "service": "github",
    "config": {
      "token": "REPLACE_WITH_GITHUB_TOKEN",
      "schema": "schema_name"
    },
    "paused": false,
    "run_setup_tests": true
  }'
  

Refer to each connector’s API reference for the exact fields.

Connectors supported by API and their authorization methods

The following table lists the connectors supported by the Fivetran REST API and the authorization methods each one supports.