Connecting HubSpot to Workflood: Required Scopes & Setup Guide
Learn how to connect your HubSpot portal to Workflood using 1-Click OAuth or Private App Access Tokens, and understand the required CRM and schema scopes.
Authentication Methods: OAuth vs. Private App Token
Workflood offers two secure methods to authenticate with your HubSpot portal:
- **1-Click HubSpot OAuth (Recommended for standard portals):** Workflood requests granular scopes through HubSpot's official OAuth 2.0 flow. Tokens are automatically refreshed and encrypted with workspace-specific keys.
- **Private App Access Token (Recommended for Enterprise / Agency setups):** Generate a Private App token inside your HubSpot portal settings with exact read/write permissions for specific CRM objects.
Both connection types store your credentials using **libsodium XChaCha20-Poly1305** symmetric encryption with per-workspace Data Encryption Keys (DEKs).
Required Scopes by Use Case
Depending on the objects your custom actions interact with, ensure your HubSpot Private App includes the appropriate OAuth scopes:
| Object / Feature | Required Scopes | Description |
|---|---|---|
| **Contacts** | crm.objects.contacts.read, crm.objects.contacts.write | Read/update contact properties, lifecycle stages, and owners |
| **Companies** | crm.objects.companies.read, crm.objects.companies.write | Deduplicate domains, update parent accounts, and assign tiers |
| **Deals** | crm.objects.deals.read, crm.objects.deals.write | Calculate commissions, create renewals, update deal health scores |
| **Owners & Users** | crm.objects.owners.read | Round-robin routing and territory assignment |
| **Associations (v4)** | crm.schemas.contacts.read, crm.schemas.deals.read | Query and link records across standard and custom objects |
| **Marketing Events** | marketing.events.read, marketing.events.write | Associate event attendance to contacts and parent companies |
| **Custom Objects** | crm.objects.custom.read, crm.objects.custom.write | Manage proprietary enterprise CRM schemas |
Step-by-Step Private App Setup in HubSpot
To generate your Private App Access Token inside HubSpot:
- In your HubSpot portal, navigate to **Settings (Gear Icon) > Integrations > Private Apps**.
- Click **Create a private app**.
- Under the **Basic Info** tab, name your app (e.g., `Workflood Automation Runtime`).
- Under the **Scopes** tab, select the checkboxes for the CRM objects your workflows will read and write.
- Click **Create app** and confirm by clicking **Continue creating**.
- Copy the provided access token (`pat-na1-...` or `pat-eu1-...`).
- In Workflood, navigate to **Connected Apps > Connect HubSpot**, select **Private App Token**, paste your token, and click **Verify & Save**.
// Verification action automatically run upon connecting
export default async function main() {
const accountInfo = await hubspot.client.crm.owners.ownersApi.getPage(1)
return {
connected: true,
activeOwnersCount: accountInfo.results.length,
portalVerified: true
}
}Verifying Permissions & Troubleshooting Scopes
If an action fails with a `403 Forbidden` or `MISSING_SCOPES` error: - Check your execution run log in Workflood to identify the exact endpoint that was rejected (e.g., `/crm/v3/objects/deals`). - Revisit **HubSpot Settings > Private Apps**, edit your app scopes, add the missing scope, and save. No need to update the token in Workflood—the changes take effect immediately on HubSpot's side.
Lead Routing
Route incoming leads to the right HubSpot owner based on territory or round-robin.
Frequently Asked Questions
Does Workflood count against my HubSpot API rate limits?
Workflood uses HubSpot API endpoints directly under your portal. HubSpot standard tier allows 100 requests per 10 seconds (or up to 150/s on API add-ons). Workflood includes automated backoff and retry handling to protect your quota.
Can I connect a HubSpot Sandbox portal for testing?
Yes. Workflood Single Portal and Agency plans allow connecting both your production portal and dedicated HubSpot Developer Sandbox portals to test actions safely.