Use the HubSpot OAuth scopes model and private app tokens to implement least-privilege access for a CRM integration
domain: developers.hubspot.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Enumerate the exact HubSpot API scopes your integration needs by reviewing the permissions table for each API endpoint you call
For a server-to-server integration create a Private App in HubSpot and select only the required scopes at creation time
Copy the private app token from the Auth tab and store it securely; use it as a Bearer token in the Authorization header
For user-installed integrations implement the standard OAuth 2.0 authorization code flow, requesting only required scopes in the authorize URL
Handle token refresh using the refresh token against the HubSpot token endpoint before the access token expires
Periodically audit the scopes in use; remove scopes that are no longer needed to reduce the blast radius of a credential leak
Known gotchas
Private app tokens do not expire by default but are instantly invalidated if rotated or if the app is deleted; build a rotation mechanism that updates all dependent services atomically
Some HubSpot APIs require portal-level admin approval of a scope at install time even if the token technically includes it; test with a real install flow, not just a private app
Scopes granted at OAuth install time cannot be expanded without prompting the user to re-authorize; design the initial scope list carefully to avoid mid-lifecycle re-auth prompts
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?