OAuth2

Here are all details about configuring Connectors to authenticate with OAuth2

Introduction

Before getting started with further details, it is very helpful to understand on a high level how OAuth2 works, this will make the following details easier to grasp and helps tremendously with troubleshooting.

Redirect URI

The redirect URI is always https://api.locoia.com/v1/oauth2/callback/connectorname for Connectors with one word names. For connectors with multiple words, spaces are replaced by %20.

Examples

• HubSpot: https://api.locoia.com/v1/oauth2/callback/hubspot

• Teamwork CRM: https://api.locoia.com/v1/oauth2/callback/teamwork%20crm

Header

The header for OAuth2 almost always looks the same for all Connectors:

{
  "encode": false,
  "token_in_header": true,
  "content_type": "application/json",
  "header_key": "Authorization",
  "token_format": "{{token}}",
  "token_prefix": "Bearer {{token_format}}"
}

Authentication Configuration

For APIs that follow the OAuth2 standard without any deviations, the Authentication Configuration looks likes this:

{
  "oauth2": {
    "auth_form": {},
    "config": {
      "client_id": "client id for oauth2 app",
      "client_secret": "client secret for oauth2 app",
      "extra_authorization_url": {
        "response_type": "code"
      },
      "extra_access_url": {
        "grant_type": "authorization_code"
      },
      "step1_authorize_url": "https://.../authorize",
      "step3_access_url": "https://.../token",
      "token_refresh_url": "https://.../token"
    }
  }
}

For APIs that use scopes, scopes can be added in the extra_authorization_url dictionary, separated by spaces, like: "scope": "scope1 scope 2".

OAuth2 URLs

• step1_authorize_url is used for opening the initial authorization website (always a GET request)

• step3_access_url is the request that is being made in order to receive the access token. This is by default a POST request with content-type application/x-www-form-urlencoded.

• token_refresh_url will be deprecated for regular OAuth2 use and only added if the refresh URL differs from the regular step3_access_url.

Additional query/body parameters

As shown in the Authentication Configuration above, additional query/body parameters can be added to the different OAuth2 URLs:

• extra_authorization_url includes query string parameters on the initial authorization request to the url step1_authorize_url.

• extra_access_url includes query string parameters on the subsequent token and refresh request to the URL step3_access_url.

Dynamic base domains

To make the base domains of the URLs flexible, user input can be used together with Jinja rendering, as documented here in detail.

Handling OAuth2 deviations

In order to handle OAuth2 deviations, additional query parameters in the URLs can be used, as well as these parameters, which can be set in the config dictionary:

• client_id_and_secret_in_headers (any value) - This will send the client id and secret as Basic Auth in the headers for the access request.

• alternative_code_key - This will overwrite the default key code for the access code value

• alternative_client_id_key - This will overwrite the default key client_id for the client id value

• alternative_client_secret_key - This will overwrite the default key client_secret for the client secret value

• grant_type - This will add grant_type as an extra query/body parameter - (Deprecated)

• accept_header - This will send an Accept header with the specified value

• content_type - This will overwrite the default Content-Type value application/x-www-form-urlencoded. If the content type is set to application/json, the body will be converted to JSON

• request_method (only accepts GET) - This will overwrite the default method POST and send the parameters as query, instead of body parameters

• access_token_path - Overwrites the default path access_token to retrieve the access token from the response

Additionally, the following field can be set in the auth_form as user input - (Deprecated)

• alternative_scope - This gives users the option to specify scopes and will overwrite any scopes set in the scope query parameter

• client_id - This is needed for Connectors that require user to create their own OAuth2 app and will overwrite the client_id from the config (See Snowflake rendering for a detailed example)

• client_secret - Same as the client_id, but for the client_secret

Other fields, can also be set in the auth_form, however, they have to explicitly be added to the config in order to be rendered and used.

Examples

HubSpot - Standard with Scopes

The Authentication Configuration is the standard one, with specific scopes:

{
  "oauth2": {
    "config": {
      "client_id": "client id for oauth2 app",
      "client_secret": "client secret for oauth2 app",
      "exchange_request_body_type": "json",
      "extra_access_url": {
        "grant_type": "authorization_code"
      },
      "extra_authorization_url": {
        "response_type": "code",
        "scope": "crm.schemas.companies.write crm.schemas.contacts.write crm.schemas.deals.read crm.schemas.deals.write files crm.objects.contacts.write e-commerce crm.objects.companies.write crm.objects.companies.read crm.objects.deals.read crm.schemas.contacts.read crm.objects.deals.write crm.objects.contacts.read crm.schemas.companies.read communication_preferences.read_write crm.objects.owners.read crm.lists.write crm.lists.read"
      },
      "or_exchange_request_body_type": "data",
      "step1_authorize_url": "https://app.hubspot.com/oauth/authorize",
      "step3_access_url": "https://api.hubapi.com/oauth/v1/token",
      "token_refresh_url": "https://api.hubapi.com/oauth/v1/token"
    }
  }
}

The header is the standard header.

TikTok - Alternative client keys and access token path

TikTok has a few deviations from the OAuth2 standard:

• The client id key is app_id instead of client_id, thus alternative_client_id_key needs to be set accordingly

• The client id key is secret instead of client_secret, thus alternative_client_secret_key needs to be set accordingly

• The access token is returned inside a dictionary called data, instead of in the 'root' dictionary, thus access_token_path needs to be set accordingly

• The base domain for the access url, is always https://business-api.tiktok.com/, even though the base domain for the endpoints itself is based on the environment: https://{% if environment is defined and environment == 'Sandbox' %}sandbox{% else %}business{% endif %}-api.tiktok.com/open_api/v1.2/

The Authentication Configuration thus needs to be setup like this:

{
  "oauth2": {
    "auth_form": {
      "environment": {
        "title": "Environment",
        "type": "select",
        "required": false,
        "default": "Production",
        "enum": [
          "Production",
          "Sandbox"
        ]
      }
    },
    "config": {
      "access_token_path": "data.access_token",
      "alternative_client_id_key": "app_id",
      "alternative_client_secret_key": "secret",
      "alternative_code_key": "auth_code",
      "client_id": "client id for oauth2 app",
      "client_secret": "client secret for oauth2 app",
      "exchange_request_body_type": "json",
      "extra_access_url": {
        "grant_type": "authorization_code"
      },
      "extra_authorization_url": {
        "response_type": "code"
      },
      "or_exchange_request_body_type": "data",
      "step1_authorize_url": "https://ads.tiktok.com/marketing_api/auth",
      "step3_access_url": "https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/",
      "token_refresh_url": "https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/"
    }
  }
}