The objects available within our connector are accessible from the "cdata.hubspot" module. To use the module's objects directly:

1. Import the module as follows:
   

   import cdata.hubspot as mod

2. To establish a connection string, call the connect() method from the connector object using an appropriate connection string, such as:
   

   mod.connect("InitiateOAuth=GETANDREFRESH;")

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:

• InitiateOAuth: GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• 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 connector opens HubSpot's OAuth endpoint in your default browser. Log in and grant permissions to the application. The connector then completes the OAuth process:

1. The connector obtains an access token from HubSpot and uses it to request data.
2. Extracts the access token from the callback URL and authenticates requests.
3. Saves OAuth values in the location specified in OAuthSettingsLocation. These values persist across connections.

The connector refreshes the access token automatically when it expires.

Web Applications

Authenticating via the Web requires you to create and register a custom OAuth application with HubSpot, as described in Creating a Custom OAuth Application. You can then use the connector to get and manage the OAuth token values.

Get an OAuth Access Token

To obtain the OAuthAccessToken, set these properties:

• OAuthClientId: The client Id in your custom OAuth application settings.
• OAuthClientSecret: The client secret in your custom OAuth application settings.

Then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the CallbackURL to the Redirect URI you specified in your custom OAuth application settings. The stored procedure returns the URL to the OAuth endpoint.
2. Navigate to the URL that the stored procedure returned in Step 1. Log in and authorize the web application. You are redirected back to the callback URL.
3. Call the GetOAuthAccessToken stored procedure. Set the AuthMode input to WEB. Set the Verifier input to the code parameter in the query string of the redirect URI.

To connect to data, set the OAuthAccessToken connection property to the access token returned by the stored procedure. When the access token expires after ExpiresIn seconds, call GetOAuthAccessToken again to obtain a new access token.

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 connector 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 connector. 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 connector 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 connector 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.)