API overview

Overview

Hightouch exposes a REST API that lets users interact with resources like syncs, models, sources, and destinations. Though the REST API is open to all Hightouch users, we aim to build features so you don't need to rely on it directly. For example, Git Sync lets you manage workspace resources programmatically.

If you're looking to create a custom destination, it's best to use the HTTP Request destination as your base. If you find you still need to use the REST API directly, about your use case.

To start using the API, you must first create and retrieve an API key from your workspace.

Required permissions

Only a workspace admin can create an API key. See Roles for more information.

Every API key belongs to one workspace. On each request, Hightouch checks the key's permissions. Those permissions come from one of two places:

A user group — The key inherits the permissions of a user group in the workspace. Changing the group's role changes what the key can do.
All of the creator's groups — The key inherits the creator's permissions. Changing the creator's permissions changes what the key can do.

Scope a key to a group to keep it from having admin access. For example, an AI tool can use a key scoped to a group with the Workspace viewer role. The key can read syncs, models, and sources but can't create, edit, or delete them. A deployment pipeline can use a key scoped to a group whose custom role can configure syncs for only the destinations that pipeline owns.

Create an API key

From the API keys tab on the Settings page, click Add API key.
Enter a descriptive Name for your key.
Under User group, select the group whose permissions the key should have in this workspace, or select All of the creator's groups to give the key the same permissions as you.
Copy your API key and store it in a safe location. The key is only displayed once.
Click Create API key.

Once you have an API key, you can follow the API Reference documentation to start using the API.

Choose a user group

The User group field lists every group that has a role in the current workspace, for example Marketing (Workspace editor).

Organization-level groups, such as Organization admins and Organization viewers, don't appear. These groups have access to every workspace in the organization, and a key belongs to one workspace, so their permissions don't fit a single key.

Change a key's user group

You can move an existing key to a different group, or between a group and All of the creator's groups, from the key list.

From the API keys tab on the Settings page, find the key in the list.
In the User group column, select the new group.
Click Save changes in the bar at the bottom of the page, then click Confirm in the dialog.

The change takes effect after a short delay. If you move a key to a group with fewer permissions, anything that authenticates with the key may start receiving errors.

How Hightouch authorizes API keys

On every request, Hightouch confirms that the key's creator could still perform everything the key can before it applies the key's permissions.

If the key is scoped to All of the creator's groups, the key works as long as the creator is still an active user with access to the key's workspace.
If the key is scoped to a user group, the key works only if the creator meets one of these conditions in the key's workspace:
- The creator is a member of the key's group.
- The creator is a workspace admin.

This rule guarantees that a key can never do more than its creator can. A workspace admin can scope a key to any group in the workspace, including one they don't belong to. They already have permission to perform every action in the workspace, so the key can't exceed their access. If that admin is later demoted and isn't a member of the key's group, the key stops working.

When a scoped key's creator can no longer perform everything the key can, the key's row on the API keys tab shows a warning that the key has stopped working. To fix the key, do one of the following:

Move the key to a group the creator belongs to.
Add the creator back to the group.
Delete the key and create a replacement as a workspace admin.

When a group is removed from a workspace

A key scoped to a group only exists while that group has a role in the workspace. Any of these actions removes that role and deletes every key scoped to the group in that workspace:

Setting the group's role to No access on the Workspace settings > Groups page or on the group's Workspaces tab in Organization settings > Groups.
Removing the workspace from the group.
Deleting the group.

Deleting a key can't be undone. Before you remove a group's access, check the group's API keys tab in Organization settings > Groups. Move each key to another group or create a replacement key, then update whatever uses it.

Revoke an API key

Your API key provides access to sensitive Hightouch resources and should be kept secure. If you believe your API key may have been compromised, revoke it immediately.

From the API keys tab on the Settings page, select the API key or keys you want to revoke.
Select Delete selected.
In the modal that appears, select Delete.

Base URL and authentication

Send all API requests to the following base URL:

https://api.hightouch.com/api/v1

Append the endpoint path to the base URL. For example, to list syncs, send a request to https://api.hightouch.com/api/v1/syncs.

Authenticate each request by passing your API key as a bearer token in the Authorization header:

curl https://api.hightouch.com/api/v1/syncs \
  -H "Authorization: Bearer YOUR_API_KEY"

Hightouch API Rate Limits

The Hightouch API rate limit is 200 requests per 10 seconds per workspace.

TLS requirements

The Hightouch REST API requires TLS 1.2 or later. The API rejects requests that use an older protocol version.

The API supports the following cipher suites:

TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384

On July 10, 2026, Hightouch removes support for several weaker cipher suites. After that date, the API rejects requests that negotiate any of the following:

ECDHE-ECDSA-AES128-SHA256
ECDHE-RSA-AES128-SHA256
ECDHE-ECDSA-AES256-SHA384
ECDHE-RSA-AES256-SHA384

If your API client only supports the deprecated cipher suites, update it before July 10, 2026 to avoid failed requests. Most modern HTTP libraries and TLS stacks already negotiate one of the supported suites.

Tips and troubleshooting

If you encounter issues using the Hightouch API, check our status page or for assistance.

Common Errors

Authentication error: Workspace is invalid

The key's creator no longer has access to the key's workspace. This happens when the creator is deactivated, removed from the organization, or removed from every group that has a role in the workspace, for example after an SSO migration.

{
  "message": "Authentication error",
  "details": "No user found"
}

{
  "message": "Authentication error",
  "details": "Workspace is invalid"
}

Either restore the creator's access or create a replacement key as a workspace admin.

Forbidden: User is not permitted to access resource

The key authenticated, but its group doesn't have permission for the action. For example, a key scoped to a Workspace viewer group can list sources but receives this error when it tries to update one.

{
  "message": "Forbidden",
  "details": "User is not permitted to access resource."
}

Check the group's role in Organization settings > Groups. Either give the group the missing permission, or move the key to a group that has it.

If the group does have the permission, the key's creator may no longer meet the authorization rule. Check the API keys tab for a warning next to the key.