This section shows how to set up ODBC connectivity and configure DSNs on macOS.

Minimum macOS Version

The CData ODBC Driver for HubSpot driver requires macOS Sierra (10.12) or above.

Licensing the Driver

In a terminal, run the following commands to license the driver. To activate a trial, omit the <key> input.

cd "/Applications/CData ODBC Driver for HubSpot/bin"
sudo ./install-license.sh <key>

You'll be prompted for a name and password. These refer to your name and your machine's password.

Authenticating to HubSpot

HubSpot supports OAuth authentication and PrivateAppToken-based authentication.

Note: The HubspotV3 schema contains two tables that only work with PrivateAppToken authentication: QuoteAssociations and Quotes. For further information, see Data Model > HubSpot V3 Data Model > Tables.

OAuth

HubSpot provides embedded OAuth credentials that simplify connection from a Desktop application or a Headless machine. To connect from a Web application, you must create a custom OAuth application, as described in Creating a Custom OAuth Application.

To connect via OAuth from all authentication flows, you must set AuthScheme to OAuth.

The following subsections describe how to authenticate to HubSpot from the available OAuth flows. For information about how to create a custom OAuth aplication, and why you might want to create one even for auth flows that already have embedded OAuth credentials, see Creating a Custom OAuth Application.

For a complete list of connection string properties available in HubSpot, see Connection.

Desktop Applications

CData provides an embedded OAuth application that simplifies authentication at the desktop;.

You can also authenticate from the desktop via a custom OAuth application, which you configure and register at the HubSpot console. For further information, see Creating a Custom OAuth Application.

Get and Refresh the OAuth Access Token

After setting the following, you are ready to connect:

• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.
• CallbackURL (custom applications only): The redirect URI defined when you registered your custom OAuth application.

When you connect, the driver opens HubSpot's OAuth endpoint in your default browser. Log in and grant permissions to the application. The driver refreshes the access token automatically when it expires.

Headless Machines

To configure the driver to use OAuth with a user account on a headless machine, you must authenticate on another device that has an internet browser.

Do one of the following:

• Option 1: Obtain the OAuthVerifier value as described below in "Obtain and Exchange a Verifier Code".
• Option 2: Install the driver on a machine with an internet browser and transfer the OAuth authentication values after you authenticate through the usual browser-based flow, as described below in "Transfer OAuth Settings".

Option 1: Obtain and Exchange a Verifier Code

To obtain a verifier code, you must authenticate at the OAuth authorization URL.

To authenticate from the machine with an internet browser and obtain the OAuthVerifier connection property, follow the steps below.

1. Do either of the following actions:
   • If you are using the Embedded OAuth Application, call the GetOAuthAuthorizationURL stored procedure. Open the URL returned by the stored procedure in a browser.
   • If you are using a custom OAuth application, set these properties:
     • InitiateOAuth: OFF.
     • OAuthClientId: The client Id assigned when you registered your custom OAuth application.
     • OAuthClientSecret: The client secret assigned when you registered your custom OAuth application.
     Then call the GetOAuthAuthorizationURL stored procedure with the appropriate CallbackURL. Open the URL returned by the stored procedure in a browser.
2. Log in and grant permissions to the driver. You are redirected to the redirect URI. A parameter called code is appended to the redirect URI. Note the value of this parameter. You will need it later, to set the OAuthVerifier connection property.

Next, you must exchange the OAuth verifier code for OAuth refresh and access tokens.

On the headless machine, set the following connection properties to obtain the OAuth authentication values:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: Persist the encrypted OAuth authentication values to the specified location.
• OAuthVerifier: The noted verifier code (the value of the code parameter in the redirect URI).
• OAuthClientId (custom applications only): The client Id in your custom OAuth application settings.
• OAuthClientSecret (custom applications only): The client secret in the custom OAuth application settings.

Test the connection to generate the OAuth settings file, then re-set the following properties to connect:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: The location containing the encrypted OAuth authentication values. Make sure this location gives read and write permissions to the driver to enable the automatic refreshing of the access token.
• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.

Option 2: Transfer OAuth Settings

Prior to connecting on a headless machine, you must install and create a connection with the driver on a device that supports an internet browser. Set the connection properties as described above in "Desktop Applications".

After completing the instructions in "Desktop Applications", the resulting authentication values are encrypted and written to the location specified by OAuthSettingsLocation. The default filename is OAuthSettings.txt.

Test the connection to generate the OAuth settings file, then copy the OAuth settings file to your headless machine.

On the headless machine, set these properties:

• InitiateOAuth: REFRESH.
• OAuthSettingsLocation: The location of the OAuth settings file you copied from the machine with the browser. Make sure this location gives read and write permissions to the driver to enable the automatic refreshing of the access token.
• OAuthClientId (custom applications only): The client Id assigned when you registered your custom OAuth application.
• OAuthClientSecret (custom applications only): The client secret assigned when you registered your custom OAuth application.

Private App Token

To connect using a Hubspot Private App Token, set the AuthScheme property to PrivateAppToken and OAuthAccessToken to the value of your application's access token.

To generate a HubSpot Private App Token:

1. In your HubSpot account, click the settings icon in the main navigation bar.
2. In the left sidebar menu, navigate to Integrations > Private Apps.
3. Click Create private app.
4. On the Basic Info tab, configure the details of your application (name, logo, and description).
5. On the Scopes tab, select Read or Write for each scope you want your private application to be able to access. This determines the data the driver has access to retrieve. Refer to the OAuthRequiredScopes and OAuthOptionalScopes properties for recommended scopes to select.
6. After you are done configuring your application, click create app in the top right.
7. Review the information about your application's access token, click Continue creating, and then click Show token.

You can now set the retrieved token in the OAuthAccessToken property. (OAuthAccessToken is used for Private App Access Tokens and OAuth Access Tokens.)

Uninstalling the Driver

The easiest way to uninstall the driver is to open a terminal and run the included uninstall.sh script, located in the installation directory. For example:

cd "/Applications/CData ODBC Driver for HubSpot"
sudo ./uninstall.sh

Note: The script needs to be run from the installation directory.