HubSpot Install & Auth Skill

HubSpot Install & Auth

Overview

Set up the @hubspot/api-client SDK and configure authentication using private app access tokens or OAuth 2.0.

Prerequisites

Node.js 18+ or Python 3.10+
HubSpot account (free or paid)
Private app created in Settings > Integrations > Private Apps
Required scopes selected for your private app

Instructions

Step 1: Install the SDK

# Node.js (official SDK)
npm install @hubspot/api-client

# Python
pip install hubspot-api-client

Step 2: Create a Private App in HubSpot

Go to Settings > Integrations > Private Apps
Click "Create a private app"
Name your app and select scopes:
- crm.objects.contacts.read / crm.objects.contacts.write
- crm.objects.companies.read / crm.objects.companies.write
- crm.objects.deals.read / crm.objects.deals.write
- crm.objects.custom.read / crm.objects.custom.write
- crm.schemas.contacts.read (for properties)
Copy the generated access token

Step 3: Configure Environment

# .env file (add to .gitignore)
HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# .gitignore
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore

Step 4: Initialize and Verify

import * as hubspot from '@hubspot/api-client';

const hubspotClient = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
});

// Verify connection by fetching account info
async function verifyConnection() {
  try {
    const response = await hubspotClient.crm.contacts.basicApi.getPage(
      1, // limit
      undefined, // after
      ['firstname', 'lastname', 'email']
    );
    console.log(`Connected. Found ${response.results.length} contact(s).`);
    return true;
  } catch (error) {
    if (error.code === 401) {
      console.error('Invalid access token. Check HUBSPOT_ACCESS_TOKEN.');
    } else if (error.code === 403) {
      console.error('Missing scopes. Add crm.objects.contacts.read to your private app.');
    } else {
      console.error('Connection failed:', error.message);
    }
    return false;
  }
}

Step 5: OAuth 2.0 Setup (Public Apps)

// For public apps distributed to multiple HubSpot portals
const hubspotClient = new hubspot.Client();

// Step 1: Generate authorization URL
const authUrl = hubspotClient.oauth.getAuthorizationUrl(
  'your-client-id',
  'http://localhost:3000/oauth/callback',
  'crm.objects.contacts.read crm.objects.contacts.write'
);
// Redirect user to authUrl

// Step 2: Exchange code for tokens (in callback handler)
const tokenResponse = await hubspotClient.oauth.tokensApi.create(
  'authorization_code',
  code,           // from query param
  redirectUri,
  clientId,
  clientSecret
);

// Step 3: Initialize client with OAuth token
const authedClient = new hubspot.Client({
  accessToken: tokenResponse.accessToken,
});

// Step 4: Refresh tokens before expiry (tokens expire in 30 minutes)
const refreshResponse = await hubspotClient.oauth.tokensApi.create(
  'refresh_token',
  undefined,
  undefined,
  clientId,
  clientSecret,
  refreshToken
);

Output

@hubspot/api-client installed in node_modules
.env file with HUBSPOT_ACCESS_TOKEN
Verified API connection with a test call
OAuth flow configured (if building a public app)

Error Handling

| Error | Code | Cause | Solution | |-------|------|-------|----------| | 401 Unauthorized | 401 | Invalid or expired token | Regenerate token in Private Apps settings | | 403 Forbidden | 403 | Missing required scopes | Add scopes and generate new token | | 429 Too Many Requests | 429 | Rate limit exceeded | Implement backoff (see hubspot-rate-limits) | | MODULE_NOT_FOUND | -- | Package not installed | Run npm install @hubspot/api-client | | ECONNREFUSED | -- | Network blocked | Ensure outbound HTTPS to api.hubapi.com |

Examples

Python Setup

from hubspot import HubSpot

client = HubSpot(access_token=os.environ.get('HUBSPOT_ACCESS_TOKEN'))

# Verify connection
try:
    contacts = client.crm.contacts.basic_api.get_page(limit=1)
    print(f"Connected. Found {len(contacts.results)} contact(s).")
except Exception as e:
    print(f"Connection failed: {e}")

TypeScript with Strict Typing

import * as hubspot from '@hubspot/api-client';
import type {
  SimplePublicObjectWithAssociations
} from '@hubspot/api-client/lib/codegen/crm/contacts';

const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  numberOfApiCallRetries: 3, // built-in retry support
});

Resources

Next Steps

After successful auth, proceed to hubspot-hello-world for your first CRM operations.

Agent Skills: HubSpot Install & Auth

Install this agent skill to your local

Skill Files