hubspot-refresh-token
Refresh HubSpot OAuth access tokens when API requests fail due to expiration. Automates token renewal and updates process.env.PRIVATE_APP_ACCESS_TOKEN. Use only for OAuth when REFRESH_TOKEN is available and avoid multiple invocations per session.
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
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {},
"type": "object"
}
Implementation Reference
- The handler function that refreshes the HubSpot OAuth access token using the refresh token from environment variables. It makes a POST request to HubSpot's OAuth endpoint, handles errors, and updates process.env.PRIVATE_APP_ACCESS_TOKEN.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, }; } }
- Defines the input schema (empty object, no params needed) and the full tool definition including name, description, inputSchema (JSON schema from Zod), and annotations for the hubspot-refresh-token tool.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, }, };
- dist/tools/toolsRegistry.js:48-48 (registration)Registers an instance of the RefreshTokenTool with the central tools registry.registerTool(new RefreshTokenTool());