Index of every page on this site: llms.txt
All skills
Run it yourself

Authenticate production HubSpot integrations and survive the auth-side failures — 30-min token expiry storms, 500K daily rate-limit burnout, scope drift, token leakage in commits, multi-portal credential routing, OAuth refresh-token decay. Use when hardening token caching, rotating private app credentials, building a multi-portal credential router, or recovering from 429/403 auth cascades. Trigger with "hubspot auth", "hubspot token cache", "hubspot rate limit", "hubspot scope drift", "hubspot multi-portal", "hubspot OAuth refresh".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/hubspot-auth

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesAPI_REFERENCE.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

HubSpot Auth — API Reference

Endpoint catalog, token shapes, rate-limit headers, and scope catalog for HubSpot authentication. Operational patterns (caching, rotation, multi-portal) live in SKILL.md; this document is the static reference.

Token Types

Type Format Expiry Use
Private App token pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx None (rotate manually) Server-to-server; no user context
OAuth access token CIX9... 1800 seconds (30 min) User-authorized; scoped to user consent
OAuth refresh token opaque string 525,600 min (~1 year) if unused Exchanges for new access tokens

OAuth Token Endpoint

POST https://api.hubapi.com/oauth/v1/token
Content-Type: application/x-www-form-urlencoded

Authorization code exchange (first connect)

Field Required Value
grant_type yes authorization_code
client_id yes from developer portal
client_secret yes from developer portal
redirect_uri yes must match registered URI exactly
code yes code from ?code= query param in callback

Refresh token exchange (ongoing)

Field Required Value
grant_type yes refresh_token
client_id yes from developer portal
client_secret yes from developer portal
redirect_uri yes must match registered URI
refresh_token yes from prior token response

Token response (200 OK)

{
  "access_token": "CIX9...",
  "refresh_token": "abc123...",
  "expires_in": 1800,
  "token_type": "bearer"
}

Note: scope is NOT included in token response. Validate scopes separately via token-info endpoint.

Token info endpoint

GET https://api.hubapi.com/oauth/v1/access-tokens/{access_token}

Response includes scope_to_scope_description, hub_id, user, token_type, expires_in.

Error responses

Status error Meaning
400 invalid_client Wrong client ID or secret
400 invalid_grant Authorization code expired or already used
400 REFRESH_TOKEN_NOT_FOUND Refresh token expired (>1 year unused) or revoked
401 INVALID_AUTHENTICATION Token expired, malformed, or revoked
403 MISSING_SCOPES Token lacks required scope
429 RATE_LIMIT Auth endpoint rate limit hit

OAuth Authorization URL

GET https://app.hubspot.com/oauth/authorize
  ?client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope={space-separated scopes}
  &optional_scope={space-separated optional scopes}

Authorization Header

Authorization: Bearer {access_token_or_private_app_token}

Rate Limit Headers

HubSpot returns these on every response:

Header Value
X-HubSpot-RateLimit-Daily Daily quota (varies by tier)
X-HubSpot-RateLimit-Daily-Remaining Remaining today
X-HubSpot-RateLimit-Interval-Milliseconds Rolling window size (ms)
X-HubSpot-RateLimit-Max Max calls in window
X-HubSpot-RateLimit-Remaining Remaining in window
Retry-After Seconds to wait (on 429)

Rate limits by tier

Tier Burst Daily
Free / Starter 100 req/10s 250,000
Professional 150 req/10s 500,000
Enterprise 150 req/10s 500,000
OAuth apps 100 req/10s per portal varies

Auth token endpoint additional limit: 10 requests/10s.

Scope Catalog (CRM — common)

Scope Access
crm.objects.contacts.read Read contact records
crm.objects.contacts.write Create/update/delete contacts
crm.objects.companies.read Read company records
crm.objects.companies.write Create/update/delete companies
crm.objects.deals.read Read deal records
crm.objects.deals.write Create/update/delete deals
crm.objects.custom.read Read custom objects
crm.objects.custom.write Write custom objects
crm.schemas.contacts.read Read contact property definitions
crm.schemas.contacts.write Manage contact properties
crm.associations.read Read CRM associations
crm.associations.write Write CRM associations
tickets Read/write support tickets
e-commerce Read/write e-commerce data
automation Read/write workflow automations
oauth Required for OAuth public apps

Full catalog: https://developers.hubspot.com/docs/guides/apps/authentication/scopes

Private App Token Format

pat-{datacenter}-{32-char-uuid}
# Example: pat-na1-{your-uuid-here}

Datacenter codes: na1 (North America), eu1 (Europe), au1 (Australia).

The token datacenter code must match the portal's datacenter; requests to the wrong datacenter endpoint return 404.

Token Revocation

HubSpot does not expose a /revoke endpoint. To invalidate:

  • Private app token: Rotate in Settings → Integrations → Private Apps → your app → Rotate token
  • OAuth token: Disconnect the app from Settings → Integrations → Connected Apps, or the user disconnects from their account

Rotation generates a new token immediately; the old token stops working instantly.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides secure implementation patterns for HubSpot authentication, focusing on token caching, rate-limiting, and preventing credential leakage. It recommends using official libraries and secret management services. A low-severity risk surface for indirect prompt injection is identified because the skill processes external authentication tokens, though it incorporates robust validation and sanitization logic.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 months ago
What it can do
Reads files Edits files Runs commands
version
2.9.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
compatibility
Designed for Claude Code
All 7 allowed tools
ReadWriteEditBash(curl:*)Bash(jq:*)Bash(openssl:*)Grep
Other metadata
tags
[
  "hubspot",
  "oauth2",
  "authentication",
  "token-management",
  "rate-limits",
  "multi-portal"
]

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/hubspot-auth