hubspot-refresh-token
Idempotent
Refresh HubSpot OAuth access tokens when API requests fail due to expiration, automatically updating the active token for continued API access.
Instructions
🔄 Refreshes the HubSpot OAuth access token using the refresh token from environment variables.
🎯 Purpose:
- Use only when HubSpot API requests fail due to expired tokens.
- Automatically refreshes and sets the active access token in process.env.PRIVATE_APP_ACCESS_TOKEN.
- Not required for long-lived Private App tokens.
🛡️ Guardrails:
- Only use if using OAuth (i.e. REFRESH_TOKEN is present in environment).
- Do not invoke more than once per session unless a 401 Unauthorized response is received from HubSpot API.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- Executes the token refresh logic: validates environment variables, makes POST request to HubSpot OAuth endpoint, updates process.env.PRIVATE_APP_ACCESS_TOKEN on success, returns structured response.
async process() { const { CLIENT_ID, CLIENT_SECRET, REFRESH_TOKEN } = process.env; if (!CLIENT_ID || !CLIENT_SECRET || !REFRESH_TOKEN) { return { content: [ { type: 'text', text: '❌ Missing CLIENT_ID, CLIENT_SECRET, or REFRESH_TOKEN in environment.', }, ], isError: true, }; } try { 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: CLIENT_ID, client_secret: CLIENT_SECRET, refresh_token: REFRESH_TOKEN, }), }); const json = await res.json(); if (!res.ok) { throw new Error(json.message || 'Token refresh failed'); } process.env.PRIVATE_APP_ACCESS_TOKEN = json.access_token; return { content: [ { type: 'text', text: JSON.stringify({ access_token: json.access_token, expires_in: json.expires_in, refresh_token: json.refresh_token, }, null, 2), }, ], }; } catch (err) { return { content: [ { type: 'text', text: `❌ Token refresh failed: ${err instanceof Error ? err.message : String(err)}`, }, ], isError: true, }; } } - dist/tools/toolsRegistry.js:48-48 (registration)Registers an instance of the RefreshTokenTool with the central tool registry.
registerTool(new RefreshTokenTool()); - Defines the Zod input schema (empty object, relies on env vars) and ToolDefinition object with name, description, JSON schema for inputs, and annotations passed to BaseTool constructor.
const RefreshTokenSchema = z.object({}); // No inputs — uses environment variables const ToolDefinition = { name: 'hubspot-refresh-token', description: ` 🔄 Refreshes the HubSpot OAuth access token using the refresh token from environment variables. 🎯 Purpose: - Use only when HubSpot API requests fail due to expired tokens. - Automatically refreshes and sets the active access token in process.env.PRIVATE_APP_ACCESS_TOKEN. - Not required for long-lived Private App tokens. 🛡️ Guardrails: - Only use if using OAuth (i.e. REFRESH_TOKEN is present in environment). - Do not invoke more than once per session unless a 401 Unauthorized response is received from HubSpot API. `, inputSchema: zodToJsonSchema(RefreshTokenSchema), annotations: { title: 'Refresh HubSpot OAuth Token', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false, }, };