Skip to content
Try for free
On this page

HubSpot

HubSpot private app tokens

Set up a HubSpot private app with a scoped access token to use HubSpot in Sim workflows

Connect HubSpot with a private app access token created by a super admin. Select the CRM scopes your workflows need and keep the creating admin's account permissions in mind when managing the app.

Legacy app availability

HubSpot ended legacy private-app creation on September 28, 2026 for accounts created on or after that date. Creation ends on October 26, 2026 for older accounts. Existing legacy private apps continue to work; the creation steps below apply only while the option remains available in your account.

For a new Sim connection when that option is unavailable, use HubSpot OAuth. HubSpot recommends Service Keys for new direct integrations, but this guide does not establish that those keys are compatible with Sim’s private-app-token connection.

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.

Set up the private app

1. Create the private app

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

    Existing private apps are under Development → Legacy apps. Creation availability is described above. If you don't see Development, look for Private Apps under Settings → Integrations in older portals.

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

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

  4. 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):

text
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:

text
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.

Add the private app token to Sim

  1. Open Integrations from your workspace sidebar

  2. Search for "HubSpot" and open it, then click Add to Sim and choose Add private app token

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

  4. Click Add private app token. Sim checks HubSpot’s token-info endpoint and, for ambiguous responses, its Account Information API — if it fails, you'll see a specific error explaining what went wrong.

Use the credential in workflows

Add a HubSpot block or the HubSpot CRM Trigger to your workflow. In the credential dropdown, select the saved HubSpot private app token. Configure the operation and its required fields. Private app tokens also work with the polling trigger. If the creating admin leaves or loses permissions, follow the account-management guidance above.

The block calls api.hubapi.com using the private app token — the same API requests used by the OAuth connection. Availability depends on the app’s scopes and account access.

Rotate 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.

Handle permission failures

A successful connection does not prove access to every CRM operation. For HTTP 403 with MISSING_SCOPES, add the scopes named in the error, save the app’s scope changes, and retry. Account downgrades can also remove access to features even when the token string stays unchanged.

If the creating user is removed and calls return USER_DOES_NOT_HAVE_PERMISSIONS, have a super admin rotate the token and update Sim, or restore that user’s access where appropriate. See HubSpot’s legacy private-app guidance.

Was this helpful?
Suggest an edit