Skip to main content

Setup Guide

This guide walks you through creating a HubSpot developer app and obtaining the OAuth 2.0 credentials required to use the HubSpot CRM Engagements Calls connector.

Prerequisites​

Step 1: Log in to the HubSpot developer portal​

Log in to your HubSpot developer account.

Step 2: Create a developer test account (optional)​

Developer test accounts let you test apps and integrations without affecting real HubSpot data.

  1. Select Test accounts in the left sidebar.

    Test accounts section

  2. Select Create developer test account.

    Create developer test account

  3. Provide a name and select Create.

    Name the test account

  4. The new account appears in the test accounts list.

    Test account portal

note

Developer test accounts are for development and testing only. Do not use them in production.

Step 3: Create a HubSpot app​

  1. Navigate to Apps in the left sidebar and select Create app.

    Create app

  2. Enter a public app name and description.

    App name and description

Step 4: Set up authentication​

  1. Go to the Auth tab.

    Configure authentication

  2. Scroll down to Scopes and select Add new scopes.

    Scopes section

  3. Add the following scopes:

    • crm.objects.contacts.read
    • crm.objects.contacts.write

    Add scopes

  4. Under Redirect URL, add your redirect URL and select Create App.

    Redirect URL

Step 5: Get the client ID and client secret​

In the Auth tab, copy the Client ID and Client Secret.

Client ID and client secret

Step 6: Get the refresh token​

  1. Construct the authorization URL:

    https://app.hubspot.com/oauth/authorize?client_id=<YOUR_CLIENT_ID>&scope=<YOUR_SCOPES>&redirect_uri=<YOUR_REDIRECT_URI>

  2. Open the URL in a browser, select your developer test account, and authorize the app.

    Auth config screen

  3. Copy the authorization code from the redirect URL.

  4. Exchange the code for tokens:

    curl --request POST \
      --url https://api.hubapi.com/oauth/v1/token \
      --header 'content-type: application/x-www-form-urlencoded' \
      --data 'grant_type=authorization_code&code=<CODE>&redirect_uri=<YOUR_REDIRECT_URI>&client_id=<YOUR_CLIENT_ID>&client_secret=<YOUR_CLIENT_SECRET>'

  5. Copy the refresh_token from the response.

tip

Store the client ID, client secret, and refresh token securely. Use Ballerina's configurable feature and a Config.toml file to supply them at runtime.