# HubSpot private app tokens (/integrations/hubspot-service-account) 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 \[#legacy-app-availability] HubSpot [ended legacy private-app creation](https://developers.hubspot.com/changelog/legacy-private-app-creation-sunset) 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](/integrations/hubspot-setup). 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 \[#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. Warning: The token is tied to the super admin who created the private app. If that user is later removed from the portal (or its permissions change), 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. ## Set up the private app \[#setting-up-the-private-app] ### 1. Create the private app \[#1-create-the-private-app] 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. 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 \[#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 \[#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. Warning: 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. ## Add the private app token to Sim \[#adding-the-private-app-token-to-sim] Open **Integrations** from your workspace sidebar Search for "HubSpot" and open 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 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 \[#using-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 \[#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. ## Handle permission failures \[#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](https://developers.hubspot.com/docs/apps/legacy-apps/private-apps/overview).