HubSpot Private App Tokens

HubSpot private apps let your workflows authenticate to HubSpot with a portal-level access token instead of a person's OAuth login. A super admin creates the app once, picks exactly the scopes it needs, and the token stays valid until it's rotated or revoked — no OAuth consent to expire, and permissions that are auditable from HubSpot's settings.

This is the recommended way to use HubSpot in production workflows: the token doesn't auto-expire, its scopes are explicit, and it can be rotated on a schedule without touching anyone's personal account.

Prerequisites

You need a HubSpot super admin to create the private app. Private apps can only be created and managed by super admins in the portal.

The token is tied to the super admin who created the private app. If that user is later removed from the portal (or loses super admin), some API calls start failing with USER_DOES_NOT_HAVE_PERMISSIONS — association calls are commonly reported. Create the app from an account you expect to keep, and rotate the token if the creator ever leaves.

Setting Up the Private App

1. Create the Private App

In HubSpot, navigate to Development in the left sidebar, then Legacy apps

HubSpot moved private apps under a new Development area and relabeled them "Legacy apps". The tokens themselves remain fully supported — only the navigation changed. If you don't see Development, look for Private Apps under Settings → Integrations in older portals.

Click Create legacy app in the top right, select Private, and give it a name (e.g. sim-hubspot-bot) and description

Open the Scopes tab and select the scopes your workflows need (see the list below)

Click Create app, confirm, and copy the access token from the app's Auth tab

2. Choose Scopes

Private apps use the same scope catalog as HubSpot OAuth apps. Grant only what your workflows use. The full set Sim's HubSpot tools can draw on is:

CRM objects (read/write as needed):

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.line_items.read
crm.objects.line_items.write
crm.objects.appointments.read
crm.objects.appointments.write
crm.objects.owners.read
crm.objects.users.read
crm.objects.marketing_events.read
crm.objects.quotes.read
crm.objects.carts.read

Tickets, emails, and lists:

tickets
sales-email-read
crm.lists.read
crm.lists.write

Ticket tools need tickets, email tools need sales-email-read, list tools need crm.lists.*, and each object type's tools need its crm.objects.* scope. Notes and association tools need the CRM object scopes of the records involved. A missing scope surfaces at run time as a 403 error with category MISSING_SCOPES naming the scopes required — widen the app's scopes from the same Scopes tab, commit the change in HubSpot, and re-run the workflow. If the 403 persists, rotate the token and update the credential in Sim.

Sim's OAuth flow also requests an oauth scope — that one is OAuth-app-only and doesn't exist for private apps. You don't need it and can't grant it.

3. Copy the Token

The token looks like pat-na1-… (North America) or pat-eu1-… (EU data residency). Both work — Sim calls api.hubapi.com, which serves both regions.

The access token is bearer credentials for your entire portal, limited only by its scopes. Treat it like a password — do not commit it to source control or share it publicly. Sim encrypts the token at rest.

Adding the Service Account to Sim

Open your workspace Settings and go to the Integrations tab

Search for "HubSpot Service Account" and click it, then click Add to Sim and choose Add private app token

Paste the Private app access token, and optionally set a display name and description

Click Add private app token. Sim verifies the token against HubSpot's token-info endpoint — if it fails, you'll see a specific error explaining what went wrong.

Using the Service Account in Workflows

Add a HubSpot block to your workflow. In the credential dropdown, your HubSpot service account appears alongside any OAuth credentials. Select it and configure the block as you normally would.

The block calls api.hubapi.com using the private app token — exactly the same requests as the OAuth flow, so every HubSpot tool works unchanged, subject to the scopes you granted.

Rotating the Token

Private app tokens don't auto-expire, but HubSpot recommends rotating them every six months and emails super admins once a token hasn't rotated in about 180 days. From the app's Auth tab you can:

Rotate and expire now — the old token dies immediately
Rotate and expire later — the old token keeps working for 7 days while you migrate

Prefer the 7-day option: rotate in HubSpot, paste the new token into the credential in Sim, confirm your workflows run, and let the old token lapse.

Common Questions

Private app tokens don't expire on their own and don't depend on any user staying logged in or re-consenting. A super admin issues them with explicit scopes, and they're stable until rotated — which is what you want for an automated workflow.

No. Only super admins can create and manage private apps in a HubSpot portal.

The private app is missing a scope that tool needs. The error names the required scopes (category MISSING_SCOPES). Add them on the app's Scopes tab in HubSpot, commit the change, and re-run the workflow. If the 403 persists, rotate the token and update the credential in Sim.

No. The prefix reflects your portal's data residency region. Sim handles both — all requests go to api.hubapi.com, which serves both regions.

The token keeps validating, but calls that check user permissions can start failing with USER_DOES_NOT_HAVE_PERMISSIONS — association calls are commonly reported. Have another super admin rotate the token (or recreate the app) and update the credential in Sim.

In the private app's Auth tab, choose Rotate and expire later (7-day grace), paste the new token into the credential in Sim, verify your workflows, and let the old token expire. Use Rotate and expire now only if the token may be compromised.

HubSpot Private App Tokens

Common Questions

On this page