HubSpot Auth — Implementation Guide
Production patterns for auth integration across languages, secret store integrations, token rotation runbook, and OAuth flow implementation. The TypeScript token-cache and multi-portal router patterns live in SKILL.md; this document covers Python equivalents, secret store wiring, and the rotation runbook.
Python Implementation
Private app (server-to-server)
import os
from hubspot import HubSpot
from hubspot.crm.contacts import ApiException
client = HubSpot(access_token=os.environ["HUBSPOT_ACCESS_TOKEN"])
def verify_token() -> bool:
try:
page = client.crm.contacts.basic_api.get_page(limit=1)
return True
except ApiException as e:
if e.status == 401:
print("Token invalid or revoked")
elif e.status == 403:
print(f"Scope missing: {e.body}")
return FalseOAuth token cache (Python)
import time
import threading
import requests
_lock = threading.Lock()
_token: str | None = None
_expires_at: float = 0.0
def get_access_token() -> str:
global _token, _expires_at
# Refresh at 80% TTL (1800s * 0.8 = 1440s; refresh at 360s before expiry)
with _lock:
if _token and time.time() < _expires_at - 360:
return _token
_token, _expires_at = _refresh_token()
return _token
def _refresh_token() -> tuple[str, float]:
resp = requests.post(
"https://api.hubapi.com/oauth/v1/token",
data={
"grant_type": "refresh_token",
"client_id": os.environ["HUBSPOT_CLIENT_ID"],
"client_secret": os.environ["HUBSPOT_CLIENT_SECRET"],
"redirect_uri": os.environ["HUBSPOT_REDIRECT_URI"],
"refresh_token": _load_refresh_token(),
},
)
resp.raise_for_status()
body = resp.json()
_validate_scopes(body)
return body["access_token"], time.time() + body["expires_in"]
def _validate_scopes(token_info: dict) -> None:
# Call token-info endpoint to get granted scopes
info = requests.get(
f"https://api.hubapi.com/oauth/v1/access-tokens/{token_info['access_token']}"
).json()
granted = set(info.get("scopes", []))
required = {"crm.objects.contacts.read", "crm.objects.deals.read"}
missing = required - granted
if missing:
raise ValueError(f"Scope drift: missing {missing}")Secret Store Integrations
AWS Secrets Manager
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
const sm = new SecretsManagerClient({ region: process.env.AWS_REGION });
async function readSecret(secretId: string): Promise<string> {
const { SecretString } = await sm.send(
new GetSecretValueCommand({ SecretId: secretId })
);
return SecretString!;
}
// For rotation: update the secret, then signal process
async function rotateHubSpotToken(newToken: string): Promise<void> {
const { PutSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
await sm.send(new PutSecretValueCommand({
SecretId: "hubspot/access-token",
SecretString: newToken,
}));
// Invalidate in-process cache
cached = null;
}GCP Secret Manager
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
PROJECT = os.environ["GCP_PROJECT"]
def read_secret(name: str) -> str:
resource = f"projects/{PROJECT}/secrets/{name}/versions/latest"
response = client.access_secret_version(request={"name": resource})
return response.payload.data.decode("utf-8")
def write_secret(name: str, value: str) -> None:
parent = f"projects/{PROJECT}/secrets/{name}"
client.add_secret_version(
request={"parent": parent, "payload": {"data": value.encode()}}
)Environment variable (local dev / simple deploys)
# Load from .env file (never committed)
export HUBSPOT_ACCESS_TOKEN="$(pass show hubspot/access-token)"
export HUBSPOT_CLIENT_ID="$(pass show hubspot/client-id)"
export HUBSPOT_CLIENT_SECRET="$(pass show hubspot/client-secret)"OAuth Public App Flow
Step 1: Authorization URL
function buildAuthUrl(state: string): string {
const params = new URLSearchParams({
client_id: process.env.HUBSPOT_CLIENT_ID!,
redirect_uri: process.env.HUBSPOT_REDIRECT_URI!,
scope: [
"crm.objects.contacts.read",
"crm.objects.contacts.write",
"crm.objects.deals.read",
].join(" "),
});
// state param prevents CSRF — generate per-session random string
params.set("state", state);
return `https://app.hubspot.com/oauth/authorize?${params}`;
}Step 2: Callback handler
// Express/Next.js route: GET /oauth/callback?code=...&state=...
async function handleCallback(code: string, state: string, sessionState: string) {
if (state !== sessionState) throw new Error("OAuth state mismatch (CSRF check)");
const res = await fetch("https://api.hubapi.com/oauth/v1/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
client_id: process.env.HUBSPOT_CLIENT_ID!,
client_secret: process.env.HUBSPOT_CLIENT_SECRET!,
redirect_uri: process.env.HUBSPOT_REDIRECT_URI!,
code,
}),
});
if (!res.ok) throw new Error(`Token exchange failed: ${await res.text()}`);
const { access_token, refresh_token, expires_in } = await res.json();
// Persist refresh token to secret store
await writeSecret(`hubspot/refresh-token/${portalId}`, JSON.stringify({
token: refresh_token,
lastUsed: Date.now(),
}));
// Seed the cache
cached = { value: access_token, expiresAt: Date.now() + expires_in * 1000 };
}Token Rotation Runbook
Use when a private-app token has been leaked (found in git history, logs, or error messages) or when rotating on schedule.
Time to complete: ~5 minutes. No downtime with staged rotation.
Assess blast radius
# Find all systems using this token grep -r "pat-na1-" ~/.env* || true # Check logs for accidental token output grep "pat-na1-" /var/log/app/*.log || trueGenerate new token
- Go to HubSpot → Settings → Integrations → Private Apps → your app → Auth tab
- Click "Rotate token" — HubSpot generates a new token and immediately revokes the old one
- Copy the new token
Update secret store (before any process restarts)
# AWS aws secretsmanager put-secret-value --secret-id hubspot/access-token --secret-string "pat-na1-NEW..." # GCP echo -n "pat-na1-NEW..." | gcloud secrets versions add hubspot-access-token --data-file=- # pass pass edit hubspot/access-tokenInvalidate in-process cache (trigger hot reload or restart)
# If SIGHUP is wired to reload secrets: kill -HUP $(pgrep -f your-service) # Or restart systemctl restart your-serviceVerify new token
curl -s "https://api.hubapi.com/crm/v3/objects/contacts?limit=1" \ -H "Authorization: Bearer pat-na1-NEW..." | jq '.results | length' # Should return 0 or 1, not an errorRemove leaked token from git history (if applicable)
git filter-branch --force --index-filter \ "git rm --cached --ignore-unmatch .env" \ --prune-empty --tag-name-filter cat -- --all git push origin --force --all # Notify all collaborators to re-clone
Monitoring Recommendations
Log these events to detect auth failures before they cascade:
| Event | Log level | Action |
|---|---|---|
| Token refresh succeeded | DEBUG | — |
| Token refresh failed (will retry) | WARN | Alert if 3 consecutive failures |
| Scope drift detected | ERROR | Page on-call; portal admin required |
| Daily rate limit at 80% | WARN | Throttle non-critical calls |
| Daily rate limit exhausted | CRITICAL | Stop all non-essential requests |
| Refresh token age > 300 days | WARN | Schedule user reconnect before day 365 |
// Structured log example
console.log(JSON.stringify({
event: "hubspot_token_refresh",
portal: portalSlug,
success: true,
expiresIn: expires_in,
dailyRemaining: parseInt(res.headers.get("X-HubSpot-RateLimit-Daily-Remaining") ?? "0"),
}));