HubSpot 403: insufficient permissions" private app

TL;DR

The token is valid but the private app was not granted the scopes the endpoint needs. Open the private app settings, add the missing scopes, and the 403 clears immediately. No code change is needed; this is pure configuration.

Error

{
  "status": "error",
  "message": "This app is not authorized for this API",
  "correlationId": "aaaa-bbbb-cccc"
}

Steps

1. Confirm the token works at all: a call to an endpoint you know is scoped should return 200. Expected: proves this is scopes, not auth.
2. In HubSpot, open the private app and check its scopes against the endpoint's documented requirements. Expected: you spot the missing scope, for example crm.objects.companies.write.
3. Add the missing scopes and save. Expected: the app's effective permissions update immediately.
4. Retry the failing call. Expected: 200 instead of 403.
5. Document the scope set your agent needs and review it when adding new endpoints. Expected: no more scope whack-a-mole.

When to use

• HubSpot API returns 403 with a working token.
• A new endpoint fails while older ones succeed on the same app.
• An agent gained a new capability and its writes started 403ing.

When not to use

• 401 errors (bad or expired token).
• 429 errors (rate limits).
• Salesforce permission errors (different platform).

Tool compatibility

• HubSpot private apps and all CRM API v3/v4 endpoints.
• Any HTTP client.

Variant phrasings

This app is not authorized for this API

The long form; add scopes in the app settings.

403 on write but 200 on read

The read scope exists but the write scope is missing.

Why it happens

Private apps follow least privilege: they can only call what their scopes allow. New endpoints need new scopes, and the 403 is the platform enforcing the boundary.

Edge cases

• Some endpoints need two scopes (object plus association); the docs list both.
• Scope changes apply immediately; no token rotation needed.
• Test apps and production apps have separate scope sets; promoting code without promoting scopes breaks prod.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tsHgvqXG3Eq1z10SihwURQ