🟢 HubSpot Developer Practical Textbook — 2026 Edition Developer Edition
Chapter 0  ·  Introduction

For HubSpot developers
Overall map

An overview of the Developer Portal, authentication methods, obtaining a Private App Token, and setting up the development environment. This chapter covers all the "maps" you need to know before starting API development for HubSpot.

Target: Internal engineers and HubSpot developers
Level: Beginner to intermediate
Time required: Approximately 60 minutes
0-1 About this textbook

Check the target audience, learning objectives, and overall structure.

📖 Target audience

I use HubSpot for work, and am using API, CLI, and custom code.More advanced automation, expansion, and integrationIt is aimed at engineers who want to realize the following. It is assumed that you have some understanding of the basic operations of each Hub such as CRM, Marketing, and CMS.

🎯 What you can learn from this textbook

From the big picture of HubSpot API to custom object design, CMS theme development, workflow extension, webhook design, OAuth app development, and AI-driven development using HubSpot MCP Server. You can systematically learn knowledge and code examples that can be used immediately in practice.

Chapter 0
Overall map
Developer Portal/Authentication/Environment construction
Chapter 1
CLI & Development Workflow
CLI v8.0.0・Local development・GitHub Actions
Chapter 2
CRM API Complete Guide
Objects / Search / Associations / Batch API
Chapter 3
Marketing & CMS API
Forms / Email / Blog / HubDB API
Chapter 4
custom object design
Schema design/property types/association
Chapter 5
CMS Themes & Templates
Theme structure/HubL practice/Responsive design
Chapter 6
CMS module design
fields.json/custom module/meta.json
Chapter 7
Workflow extension
Custom Code Action・Serverless Functions
Chapter 8
Webhooks & event driven
Webhook design/signature verification/external system linkage
Chapter 9
App & OAuth design
Public App・OAuth 2.0・Marketplace application
Chapter 10
MCP Server & AI Development
HubSpot MCP/Claude Code/Cursor integration
Chapter 11
Security & Production
Token management/rate limiting/error handling
0-2 Overall picture of the HubSpot development ecosystem

Organize the layers that developers are involved with and the tools and APIs used in each layer.

AI / MCP
HubSpot MCP Server
Claude Code
Cursor
↕
development tools
HubSpot CLI v8
VS Code
GitHub Actions
Sandbox
↕
API layer
CRM API
CMS API
Marketing API
Webhooks
OAuth 2.0
↕
HubSpot
CRM / Objects
CMS Hub
Workflows
Marketing Hub
Data Hub
↕
External collaboration
SFA / ERP
data warehouse
Slack / Notion
custom app
point: When working with HubSpot as a developer, it's important to first clarify what you want to achieve at which layer. CRM API for reading and writing CRM data, CMS CLI for website customization, Webhooks for real-time integration with external systems, MCP Server is suitable for accelerating development using AI.
0-3 How to use Developer Portal

Understand the main functions of the Developer Portal (app.hubspot.com), which is the starting point for development.

function place Main uses
Private App Settings → Integrations → Private Apps Access tokens for internal tools (recommended)
Public App Developer account → Apps OAuth app that connects to another company's portal
API key (old) Settings → Integrations → API Keys Not recommended. Avoid new use
Sandbox Settings → Sandbox Development/test environment that does not affect production data
API reference developers.hubspot.com Check endpoint specifications and parameters
App Marketplace ecosystem.hubspot.com Public application review/posting application
⚠ API keys are deprecated: New creation of the old API key (hapikey parameter) will be discontinued after November 2022. Whenever you update an existing integration, Private App Token Please migrate to .
0-4 How to choose an authentication method

There are three types of HubSpot API authentication depending on the purpose. Select the appropriate method depending on the situation.

Authentication method suitable case scope control Recommendation level
Private App Token Internal tools that only access your company portal ◎ Can be set in detail ★ Recommended
OAuth 2.0 Public app that connects to multiple portals ◎ User consent based standard
API key (old) Legacy integration (migration recommended) ✗ No scope control Not recommended
🔑 Features of Private App Token

A Private App Token is an access token tied to a specific HubSpot portal. at the time of creationGrant only necessary scopesThis makes it easier to follow the principle of least privilege and is ideal for internal tools from a security perspective. Tokens are used for Bearer authentication and regular rotation is recommended.

0-5　Private App Token creation procedure

The flow from actually creating a token to calling the API.

  1. 1
    Log in to your HubSpot portal Open the profile icon on the top right → “Settings (⚙)”.
  2. 2
    Open the Private Apps menu Left sidebar → "Integration" → "Private Apps" → "Create Private App".
  3. 3
    Enter app name and description Give it a descriptive name (for example:crm-sync-internal）。
  4. 4
    Select scope Check only the required permissions from the "Scope" tab. Separate Read/Write and keep privileges to minimum.
  5. 5
    Create app and copy token After clicking "Create app", copy the displayed token.Cannot be displayed againStore it in a safe place.
cURL
# API call example using Private App Token curl -X GET \ "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" \ -H "Authorization: Bearer YOUR_PRIVATE_APP_TOKEN" \ -H "Content-Type: application/json"
Scope selection tips: Without giving full scope from the beginning,crm.objects.contacts.read Let's get into the habit of assigning each function like this. You can add more later, but too wide a scope is a security risk.
0-6 Development environment setup

Set up Node.js, HubSpot CLI, and environment variables to get ready to start development.

📋 Prerequisites

Node.js 20 or higher(LTS recommended), npm, and Git are required. HubSpot CLI v8.0.0 and later will not work with Node.js below 18. node -v Please check.

Terminal
# Check Node.js version node -v # Must be v20.x.x or higher npm -v # Install the HubSpot CLI npm install -g @hubspot/cli@latest # Check version hs --version # Must be 8.x.x or higher
Terminal—CLI authentication
# Register credentials in HubSpot CLI hs auth # Enter the following interactively: # → Portal ID (portal numerical ID) # → Personal CMS Access Key or Personal Access Key # Check registered portals hs config list
.env — environment variable file
# Create .env file in project root HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HUBSPOT_PORTAL_ID=12345678 NODE_ENV=development
⚠ Do not commit .env to Git: .gitignore be sure to .env Please add. If a token is accidentally included in the repository, immediately invalidate it and issue a new one.
.gitignore
# .gitignore for your HubSpot development project node_modules/ .env .env.local .env.*.local dist/ .hubspot/ *.log
0-7 Utilization of Sandbox

Develop and test in a sandbox environment to avoid impacting production data.

kinds Features Available plans
Developer Sandbox Empty portal. No actual data. Ideal for API/CLI operation verification Free (developer account)
Standard Sandbox Contains a copy of production data. Can be tested in conditions closer to actual production Enterprise
Obtaining a developer account: developers.hubspot.com When you create a free developer account from You will be granted a Developer Sandbox portal. Do all your API development, CLI validation, and custom object testing here.
0-8 Basic knowledge of API rate limits

The HubSpot API has rate limits that result in an error if exceeded. Figure it out in advance.

Type of restriction upper limit remarks
Number of requests per 10 seconds 100 requests / 10 seconds Most common limitations. 429 error on excess
Number of requests per day Depends on plan (Free: 250,000) Enterprise can significantly increase
Burst limit 100 requests / 10 seconds Beware of bursty requests
Batch API Up to 100 items per request Mass processing becomes more efficient with Batch API
Node.js — Dealing with rate limits
// Example of retry implementation in case of 429 error (exponential backoff) async function apiCallWithRetry(fn, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fn(); } catch (error) { if (error.response?.status === 429 && attempt < maxRetries - 1) { const wait = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s... await new Promise(r => setTimeout(r, wait)); } else { throw error; } } } }
0-9 SDK selection

HubSpot provides an official SDK. Use them differently depending on the language.

language package Features Recommendation level
Node.js @hubspot/api-client official. With TypeScript type definitions. most fulfilling ★ Recommended
Python hubspot-api-client official. Frequently used for collaboration scripts with Data Hub Recommended
PHP hubspot/hubspot-php Community version. Not officially supported reference
others REST API direct call curl / fetch / axios etc. Available in all languages General purpose
Node.js — SDK setup
# install npm install @hubspot/api-client // Usage example (TypeScript/JavaScript) import { Client } from '@hubspot/api-client'; const hubspotClient = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN, }); // Get contact list const contacts = await hubspotClient.crm.contacts.basicApi.getPage( 10, // limit undefined, // after (pagination) ['email', 'firstname', 'lastname'] // properties ); console.log(contacts.results);
0-10 Summary of this chapter

Before moving on to the next chapter (CLI & Development Workflow), let's summarize the important points.

✅ Chapter 0 Checklist

  • Understood the overall picture of the HubSpot development ecosystem (API layer, tool layer, AI layer)
  • Understood the main features of the Developer Portal (Private App, Sandbox, API reference)
  • Created a Private App Token and granted only the necessary scopes
  • Confirmed that API key (old) is deprecated
  • Node.js 20 or higher + HubSpot CLI v8.x installed
  • Completed portal authentication with hs auth
  • Created a .env file and added it to .gitignore
  • You have acquired (or are planning to create) a Developer Sandbox portal.
  • Understood the concept of rate limiting (100 req/10 seconds) and exponential backoff
  • Confirmed basic usage of Node.js SDK (@hubspot/api-client)
About the next chapter (Chapter 1): Learn how to use the HubSpot CLI v8.0.0, create a local development environment, and configure a CI/CD pipeline using GitHub Actions. Build practical workflows, from basic CLI commands to automating theme and module uploads.
Chapter 1: CLI & Development Workflow →