Hubspot Auth

What it does

When your agent uses it

• Hardening token caching
• Rotating private app credentials
• Building a multi-portal credential router
• Recovering from 429/403 auth cascades

Example prompts

• “hubspot auth”
• “hubspot token cache”
• “hubspot rate limit”
• “/hubspot-auth”

Requirements

• Python 3
• Node.js
• A credential in HUBSPOT_ACCESS_TOKEN
• A credential in HUBSPOT_CLIENT_SECRET
• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(curl:*), Bash(jq:*), Bash(openssl:*), Grep

Workflow steps

6 steps, taken from the step headings in SKILL.md.

1. 1Token-cache pattern (neutralizes expiry storms)
2. 2Exponential backoff with jitter (neutralizes rate-limit burnout)
3. 3Scope validation on refresh (neutralizes scope drift)
4. 4Secret management and leak prevention (neutralizes token leakage)
5. 5Multi-portal credential router (neutralizes wrong-portal routing)
6. 6Refresh-token decay detection (neutralizes silent access loss)

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Write
  • Edit
  • Bash(curl:*)
  • Bash(jq:*)
  • Bash(openssl:*)
  • Grep

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • git
  • curl
  • jq

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Hosts in commands or code, which the agent is likely to contact:

  • api.hubapi.com

  Also links to:

  • developers.hubspot.com
  • npmjs.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • HUBSPOT_ACCESS_TOKEN
  • HUBSPOT_CLIENT_SECRET

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

Hubspot Auth loads about 3.4k tokens when it runs, and up to ~6.8k if it reads all its reference files. Until then it costs about 138 tokens; SKILL.md has 805 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~138

When it runs · the whole SKILL.md, loaded when a task matches

~3.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

• NoteMentions a .env fileSKILL.md:168

  **Never put tokens in source code, `.env` files committed to git, or log output.**

• NoteMentions a .env fileSKILL.md:172

  .env

• NoteMentions a .env fileSKILL.md:173

  .env.local

• NoteMentions a .env fileSKILL.md:174

  .env.*.local

• NoteMentions a .env fileSKILL.md:179

  it log --all --full-history --oneline -- .env

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 805 words, ~3,388 tokens.

name

hubspot-auth

description

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".

allowed-tools

Read, Write, Edit, Bash(curl:*), Bash(jq:*), Bash(openssl:*), Grep

compatibility

Designed for Claude Code

version

2.9.0

license

MIT

author

Jeremy Longshore <jeremy@intentsolutions.io>

tags

hubspot, oauth2, authentication, token-management, rate-limits, multi-portal

type Cached = { value: string; expiresAt: number };
let cached: Cached | null = null;
let inflight: Promise<string> | null = null;

export async function getToken(): Promise<string> {
  // Refresh at 80% of TTL (1800s → refresh at 1440s elapsed, i.e. 360s before expiry)
  if (cached && Date.now() < cached.expiresAt - 360_000) return cached.value;
  if (inflight) return inflight;

  inflight = (async () => {
    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: "refresh_token",
        client_id: process.env.HUBSPOT_CLIENT_ID!,
        client_secret: process.env.HUBSPOT_CLIENT_SECRET!,
        redirect_uri: process.env.HUBSPOT_REDIRECT_URI!,
        refresh_token: await loadRefreshToken(), // read from secret store
      }),
    });
    if (!res.ok) throw new HubSpotAuthError(res.status, await res.text());
    const { access_token, expires_in } = await res.json();
    cached = {
      value: access_token,
      expiresAt: Date.now() + expires_in * 1000,
    };
    return access_token;
  })().finally(() => { inflight = null; });

  return inflight;
}

class HubSpotAuthError extends Error {
  constructor(public status: number, public body: string) {
    super(`HubSpot auth failed ${status}: ${body}`);
  }
}

async function withRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 4,
  baseDelayMs = 500,
): Promise<T> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      const isRetryable =
        err.status === 429 ||
        (err.status >= 500 && err.status < 600);

      if (!isRetryable || attempt === maxAttempts) throw err;

      // Full jitter: random delay in [0, min(cap, base * 2^attempt)]
      const cap = 30_000;
      const expDelay = Math.min(cap, baseDelayMs * 2 ** attempt);
      const jittered = Math.random() * expDelay;

      // Respect Retry-After if present
      const retryAfterMs = err.retryAfterSeconds
        ? err.retryAfterSeconds * 1000
        : jittered;

      await new Promise((r) => setTimeout(r, retryAfterMs));
    }
  }
  throw new Error("unreachable");
}

// Usage
const token = await withRetry(() => getToken());

const REQUIRED_SCOPES = new Set([
  "crm.objects.contacts.read",
  "crm.objects.contacts.write",
  "crm.objects.deals.read",
]);

function validateScopes(tokenBody: any): void {
  const granted = new Set((tokenBody.scope as string).split(" "));
  const missing = [...REQUIRED_SCOPES].filter((s) => !granted.has(s));
  if (missing.length > 0) {
    throw new Error(`Scope drift detected — missing: ${missing.join(", ")}. ` +
      "A portal admin must re-grant these scopes in Private Apps settings.");
  }
}

// Call inside the token refresh:
const body = await res.json();
validateScopes(body);
cached = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };

# .gitignore — add these if not present
.env
.env.local
.env.*.local
*.pat
hubspot-credentials.json

# Verify no token is already committed
git log --all --full-history --oneline -- .env
git grep -r "pat-na1" -- '*.ts' '*.js' '*.py' '*.json'
git grep -r "HUBSPOT_ACCESS_TOKEN\s*=" -- '*.ts' '*.js'

// Health check — cheap read to verify token is live
async function verifyToken(token: string): Promise<boolean> {
  const res = await fetch("https://api.hubapi.com/crm/v3/objects/contacts?limit=1", {
    headers: { Authorization: `Bearer ${token}` },
  });
  return res.status === 200 || res.status === 204;
}

// credentials.json (in secret store, NOT in git)
// { "portals": { "acme-corp": "pat-na1-...", "beta-inc": "pat-na1-..." } }

class HubSpotRouter {
  private caches = new Map<string, { value: string; expiresAt: number }>();
  private credentials: Record<string, string>;

  constructor(credentials: Record<string, string>) {
    this.credentials = credentials;
  }

  async getClient(portalSlug: string): Promise<{ token: string }> {
    const cached = this.caches.get(portalSlug);
    // Private-app tokens don't expire — still cache to avoid repeated lookups
    if (cached) return { token: cached.value };

    const token = this.credentials[portalSlug];
    if (!token) throw new Error(`No credential for portal: ${portalSlug}`);

    // Verify the token is live before caching
    const ok = await verifyToken(token);
    if (!ok) throw new Error(`Token for portal ${portalSlug} is invalid or revoked`);

    this.caches.set(portalSlug, { value: token, expiresAt: Infinity });
    return { token };
  }
}

// Load credentials from secret store at startup
const creds = JSON.parse(await readSecret("hubspot/portal-credentials"));
const router = new HubSpotRouter(creds.portals);

// Usage
const { token } = await router.getClient("acme-corp");

// Store last-used timestamp alongside the refresh token
interface RefreshTokenRecord {
  token: string;
  lastUsed: number; // Unix ms
}

const REFRESH_TOKEN_WARN_DAYS = 300; // warn at 300d, expire at 365d

async function loadRefreshToken(): Promise<string> {
  const record: RefreshTokenRecord = JSON.parse(
    await readSecret("hubspot/refresh-token")
  );

  const ageDays = (Date.now() - record.lastUsed) / 86_400_000;
  if (ageDays > REFRESH_TOKEN_WARN_DAYS) {
    console.warn(
      `HubSpot refresh token unused for ${ageDays.toFixed(0)} days — ` +
      "reconnect the OAuth app before day 365 or access will be lost."
    );
  }

  // Update last-used timestamp
  await writeSecret("hubspot/refresh-token", JSON.stringify({
    ...record,
    lastUsed: Date.now(),
  }));

  return record.token;
}

import * as hubspot from "@hubspot/api-client";

const client = new hubspot.Client({
  accessToken: process.env.HUBSPOT_ACCESS_TOKEN!,
  numberOfApiCallRetries: 3,
});

const contacts = await client.crm.contacts.basicApi.getPage(10);

// Every outbound call goes through getToken() — cache handles the rest
async function hubspotFetch(path: string, init?: RequestInit) {
  const token = await getToken();
  return fetch(`https://api.hubapi.com${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${token}`, ...init?.headers },
  });
}

curl -s "https://api.hubapi.com/oauth/v1/access-tokens/$HUBSPOT_ACCESS_TOKEN" | jq '{hub_id, user, scopes}'

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skills/.curated/hubspot-auth of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/API_REFERENCE.md
• references/implementation-guide.md

Open the folder on GitHubat commit cfae287