Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Integrations and API

HubSpot API Basics: Private Apps, Tokens and Scopes

Learn how to call the HubSpot API safely: private app access tokens, scopes, bearer headers, OAuth for public apps, and secret handling, with a runnable request and scope-check stand-in.

HubSpot exposes almost everything in the CRM through a REST API at https://api.hubapi.com. To use it, your code must prove who it is and what it is allowed to do. For integrations that serve your own account, the standard answer is a private app; for products offered to many customers, you build a public app that uses OAuth.

The live HubSpot API cannot be called from this site (it needs your private token, and the sandbox forbids secrets). Read-only blocks show real request shapes. Runnable blocks are Python stand-ins that imitate the checks the API performs. Never paste a real token into a web page or a repository.

Private apps

Create one in Settings > Integrations > Private Apps > Create a private app:

  1. Name it and describe its purpose.
  2. On the Scopes tab pick only what you need, for example crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read.
  3. Create the app. HubSpot shows an access token once (you can view it again later in the app's settings, and rotate it). Treat it like a password.

Because a token is tied to scopes, a leaked read-only token cannot delete contacts.

Calling the API

The token goes in an HTTP Authorization header with the Bearer scheme:

Terminal
curl --request GET \
  --url "https://api.hubapi.com/crm/v3/objects/contacts?limit=2&properties=email,firstname" \
  --header "Authorization: Bearer $HUBSPOT_TOKEN"

A successful reply is JSON:

JSON
{
  "results": [
    { "id": "101", "properties": { "email": "[email protected]", "firstname": "Ana" } }
  ],
  "paging": { "next": { "after": "102", "link": "https://api.hubapi.com/..." } }
}

(The sample values are made up; the structure of results, properties and paging.next.after is how the CRM v3 objects API responds.) Common status codes:

Status Meaning
200 / 201 Success / created
400 Invalid request, bad property or filter
401 Missing or invalid token
403 Token lacks a required scope
404 Record or endpoint not found
409 Conflict, for example a contact with this email exists
429 Too many requests, slow down
5xx HubSpot-side error, retry later

Auth choices

Private app One account, scoped token
Public app (OAuth) Many accounts, user consent
API keys Retired by HubSpot
Least privilege Only the scopes you need

Secrets stay out of code

1 / 2

A scope checker (stand-in)

The stand-in below decides whether a token may call an endpoint. It does not talk to HubSpot; it shows why a 403 happens and how to read the missing scope.

Python 401 versus 403, with scopes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Keeping tokens safe

  • Store the token in an environment variable or secrets manager, never in source control.
  • Use one private app per integration so you can rotate or revoke one without breaking others.
  • Rotate tokens on a schedule and immediately if exposed.
  • Do not call the API from browser JavaScript; the token would be visible. Use a server.
  • Log request IDs, never full headers.
Python Build headers from the environment (pattern)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The example fails on purpose here because no environment variable is set, which is exactly the behavior you want in a real deployment.

OAuth and public apps

A public app is created in a developer account. A customer installs it through an authorization URL; HubSpot redirects back to your server with a code, which you exchange for an access token (short-lived) and a refresh token. You then call the API with the access token, and use the refresh token to get a new one when it expires. Scopes are shown to the user for consent. This is the route for marketplace apps; for internal scripts a private app is simpler.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which HTTP header carries a private app token?

    Private app tokens are sent as Bearer tokens.
  2. 2. You receive 403 from an endpoint. What is most likely?

    401 means unauthenticated; 403 means authenticated but not permitted.
  3. 3. Where should the token live?

    Tokens are secrets and must never reach clients or version control.

Summary

  • Private apps give a scoped bearer token for your own account; public apps use OAuth.
  • 401 means bad credentials, 403 means a missing scope.
  • Keep secrets in the environment, use least privilege, and rotate tokens.

Next: CRM API: Objects, Search and Pagination