hubspot-security-basics

# HubSpot Security Basics ## Overview Security best practices for HubSpot private app tokens, OAuth scopes, webhook signature verification, and secret management. ## Prerequisites - HubSpot private app or OAuth app configured - Understanding of environment variables and secret management ## Instructions ### Step 1: Least-Privilege Scopes Only request the scopes your integration actually uses: | Use Case | Required Scopes | |----------|----------------| | Read contacts | `crm.objects.contacts.read` | | Write contacts | `crm.objects.contacts.read`, `crm.objects.contacts.write` | | Read/write deals | `crm.objects.deals.read`, `crm.objects.deals.write` | | Marketing emails | `content` | | Forms | `forms` | | Contact lists | `crm.lists.read`, `crm.lists.write` | | Properties | `crm.schemas.contacts.read` | | Custom objects | `crm.objects.custom.read`, `crm.objects.custom.write`, `crm.schemas.custom.read` | | Webhooks | `automation` | **Never use:** Do not grant `all` scopes. If you regenerate a private app token, the old token is immediately revoked. ### Step 2: Token Storage ```bash # .env (NEVER commit) HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx HUBSPOT_WEBHOOK_SECRET=your-webhook-secret # .gitignore .env .env.local .env.*.local ``` ```typescript // Validate token is present at startup function validateConfig(): void { if (!process.env.HUBSPOT_ACCESS_TOKEN) { throw new Error('HUBSPOT_ACCESS_TOKEN is required. See .env.example'); } //...