Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My HubSpot connection stopped working and I need a new access token

Short answer

HubSpot integrations sign in with an access token sent as a Bearer header, and each private app has its own token and scopes. A token stops working when it is rotated, the app is deleted, scopes are missing or the creating user is removed. HubSpot is also closing creation of new legacy private apps and points to service keys.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • My website or app suddenly gets 401 or permission errors from HubSpot.
  • Someone left the company and the connection broke.
  • My old integration still uses an old kind of key and I was told it no longer works.
  • HubSpot will not let me create a new private app.
  • I do not know who owns the token the website uses.

Why does this happen?

  1. The token was rotated or the app deleted

    HubSpot says that rotating a private app's token creates a new one and expires the original. Choosing rotate and expire now revokes the old token immediately, and rotate and expire later expires it after 7 days. Deleting an app permanently revokes its token.

  2. The user who created the app was removed

    HubSpot states that if the creating user is removed, some calls may fail with a USER_DOES_NOT_HAVE_PERMISSIONS error. Rotating the token or re-adding the user is its documented fix.

  3. The scopes no longer cover what the integration does

    Each token has scopes that define what it can reach. HubSpot says that if an account is downgraded and loses functionality, the app loses the related scopes while the token string itself stays the same, so the token looks valid but some calls fail.

  4. HubSpot is changing how new apps are made

    HubSpot has announced that creating new legacy private apps through the account is being disabled, with one date for new accounts and another for existing ones. Existing legacy private apps are not affected for now, and HubSpot points to service keys and to the developer platform projects framework instead.

  5. The old method was never moved to a token

    An integration written for an older method still sends the old credential. It must be changed in the code to send an access token in the Authorization header as Bearer, and the token must then be stored safely outside the website's public files.

What can I do about it today?

  1. Do not delete any app or tokenDeleting a private app permanently revokes its token, which can switch off other things that use it.
  2. Find out who is a super adminHubSpot says only super admins can access private apps, so you need one of them, or to ask for access.
  3. List what uses HubSpotWebsite forms, billing tools, mail tools, reporting. Each one that logs in with a credential needs to be known.
  4. Write down when it stoppedA known time helps match it to a rotation, a removed user or an account change.
  5. Never paste a token into email or chatA token is a password to your customer data. Share it only through a password manager, and ask for a new one if it has been pasted anywhere.

When should I bring someone in?

  • Customer data is no longer flowing to or from HubSpot.
  • The person who set the integration up has left and nobody holds the token.
  • A token was shared in public, such as a public code repository.

How do I handle it?

  1. Find every place the credential is usedI search the website, server settings and connected tools for the credential, and list who owns each.
  2. Read HubSpot's current optionsBefore choosing between a private app, a service key or the developer platform, I read HubSpot's documentation for what your integration needs, such as scopes and webhooks.
  3. Create the new credential with the least scopesIt gets only the access the integration needs, is owned by your account and not a person who may leave, and is stored in the server's secrets.
  4. Switch over, test, then retire the old oneI test with the new token first, switch, check that data flows, and only then expire the old credential, so nothing is cut off early.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Will my current private app stop working?

HubSpot's announcement says existing legacy private apps are not affected for now. Read the announcement again, because dates and advice can change.

How often should a token be rotated?

HubSpot recommends rotating private app tokens every six months, and rotating one immediately if it is lost or exposed.

Can I check what a token can do?

HubSpot documents a call that returns the user, account, app and scopes for a token. A developer can use it without changing anything.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.