Authenticating SaaS Sources

A SaaS Source, such as HubSpot or Stripe, grants access to your data only to an application that it can identify. You provide the credentials that identify Hevo in the config object or, for an OAuth app of your own, in the auth object when you create the Pipeline. You can create a Pipeline for a SaaS Source through the API only when you can send all of its credentials in the request, without signing in through a browser.

A SaaS Source accepts the following credential types:

• A token that you create in the Source itself and that does not expire.
• The credentials of an OAuth app that you register with the Source.

Refer to the following sections to authenticate your SaaS Source:

• Finding the Credential Type: Read the connector configuration to see which credential type your Source accepts.
• Static Token: Send a credential that you create in the Source and that does not expire.
• Your Own OAuth App: Register an OAuth app with the Source and send its client ID, client secret, and token.
• Sources you Cannot Authenticate Through the API: Identify the Sources that require a browser sign-in, and configure them in the Hevo UI.
• Rotating Credentials: Replace the credentials of an existing Source without recreating the Pipeline.

Prerequisites

• An active Hevo account. You can start with a 14-day full-feature, free trial account.
• You are assigned the required role for the endpoint you want to use.
• You have generated your API credentials. Read Authentication for the steps to generate them.
• You have created the credentials for your SaaS Source in the Source itself.

Finding the Credential Type

The credential type a Source accepts is part of its connector configuration. Read Creating a Pipeline with Hevo API for the steps to call the Get Configuration Details of a Source Connector endpoint.

Call the endpoint with your connector_id, and read the response in the following way:

• If the schema has an auth property at the top level, the connector accepts the credentials of your own OAuth app in source.auth.
• A credential listed inside config and marked writeOnly is a static credential that you send in config.
• If the response has an authentication_method field, the values in its oneOf list are the credential types that you can choose from. The OAUTH value means that you send auth. Refer to Static Token or Your Own OAuth App for the steps, depending on the value that you select.
• A connector that has no auth property and no static credential cannot be set up through the API.

A connector can accept more than one credential type. For example, HubSpot takes a private app token or your own OAuth app, and you choose between them with authentication_method.

A connector may require additional or different credentials. Following are some examples:

• Microsoft Ads requires an additional developer_token alongside the OAuth credentials. Send it inside auth.client_access, next to client_id and client_secret. Hevo does not check for this token when it reads the request, but the Source connection test fails without it, and the request that creates the Pipeline returns an error.
• Google Ads requires a customer_id, which you send in config.
• Amazon Selling Partner requires an additional application_id. Send it inside auth.client_access, and send the subdomain value, which is NA, EU or FE, in config.
• Facebook Ads accepts auth.access_token only when config.auth_method is GRANT_USER_ACCESS, which is the default. With SYSTEM_USER_TOKEN, send the token in config.access_token instead.
• TikTok Ads does not capture your advertiser list when you authorize through the API, so set config.sync_mode to SPECIFIC_ADVERTISERS and list the advertiser IDs in config.selected_advertisers.
• Facebook Ads and TikTok Ads take a long-lived access_token instead of a refresh token, and Hevo uses this token to connect to the Source. For Facebook Ads, the token expires after about 60 days, and Hevo renews it for you before it expires. For TikTok Ads, the token does not expire.

For a Source that is not a SaaS application, such as a database, you do not use these credential types. Instead, you send its connection details, such as the host name, port, and database user, in the config object.

Static Token

A static token is a single credential that you create in the Source itself, such as a Stripe API key or a HubSpot private app access token. It does not expire, so you send it once in the config object and Hevo continues to use it until you replace it.

The shape of the config object depends on the connector.

Some connectors take the token directly, with no authentication_method to select. The following example sends an api_key for a Stripe Source:

"config": {
  "api_key": "<your token>"
}

Other connectors ask you to select a method first, because they also support OAuth. The following example sends a private app token for a HubSpot Source:

"config": {
  "authentication_method": "PRIVATE_APP_TOKEN",
  "account_id": 12345678,
  "private_app_access_token": "<your token>",
  "client_secret": "<your client secret>"
}

Your Own OAuth App

An OAuth app is an application that you register with the Source so that Hevo can connect to it on your behalf. Instead of a single token, you send the credentials of that app.

You register the app with the Source, obtain a refresh token from it once, and send that token along with the app's client ID and client secret. The following example sends the credentials of an OAuth app:

"auth": {
  "client_access": {
    "client_id": "<your client id>",
    "client_secret": "<your client secret>"
  },
  "refresh_token": "<your refresh token>"
}

When you create the Pipeline, Hevo uses these credentials to obtain an access token from the Source. Hevo renews this token for you from then on, so you do not have to send the credentials again. Some connectors take an access_token in place of a refresh token, and Hevo uses that token directly.

Hevo does not return these credentials, or any other Source configuration, in a response. Keep your own copy of each credential that you send.

Sources you Cannot Authenticate Through the API

Some Sources can only be authorized by signing in through a browser, which the API cannot do. The configuration details of such a connector offer no credential that you can send in config. Its schema has no auth property, which is how you identify such a connector. Sending auth to it returns a 400 error.

Configure those Sources in the Hevo UI. Only the authorization requires the UI. Once the Pipeline is created, you can read and manage it through the API.

Rotating Credentials

Hevo connects to your Source with the credential that you sent when you created the Pipeline. To rotate that credential, you create a new credential in the Source and send it to Hevo, which then connects with the new credential instead of the old one. The Pipeline and the Source are not recreated. You may have to rotate a credential in the following scenarios:

• The credential is revoked in the Source.
• A client secret is regenerated.
• Your own security policy requires it.

Send the new credentials to the Modify Source Configuration in a Pipeline (PATCH) endpoint, in the same form as when you created the Pipeline. For an OAuth Source, send an auth object that contains your app’s client_id and client_secret under client_access, along with a refresh_token or an access_token. A body that sends only auth is valid, so you need not send config at all. Credentials sent in config are not exchanged for a token. A static token, such as an API key or a private app token, is rotated in config.

You can rotate credentials only while the Pipeline is Initialized or Disabled. A Pipeline in the Failed state returns a 400, and a Pipeline that is changing state returns a 409. Changing config.authentication_method without sending auth in the same request returns a 400 error, because the change voids the current authorization.

Note:

• If an edit started in the Hevo UI is open for this Pipeline, the request returns a 409 until that edit is submitted or canceled.
• Sending auth for a connector that does not support OAuth returns a 400. An OAuth connector that Hevo cannot authorize through the API also returns a 400. Update the credentials of such a connector in the Hevo UI.

Hevo does not apply the new credentials immediately. It first tests them against the Source. If you send the credentials of your own OAuth app, Hevo exchanges them for a new access token before the test. If the test succeeds, Hevo saves the new credentials and stops using the replaced ones, but it does not delete the replaced token. If the test fails, the request returns a 400 that states the reason, and Hevo deletes the new access token that it generated. Nothing is saved, and the Pipeline continues to use the credentials that it already has.