​

OAuth Scopes Reference

Quick reference for which HubSpot permissions (scopes) each action needs.

---

​

What Are OAuth Scopes?

OAuth scopes are permissions you grant when connecting HubSpot to Agent.AI. Each scope allows specific actions. Example:

• crm.objects.contacts.read = View contacts
• crm.objects.contacts.write = Create/update contacts

---

​

Required Scopes by Action

​

Search HubSpot (V2)

Action: Search for contacts, deals, companies, or tickets Required scopes:

• Contacts: crm.objects.contacts.read
• Deals: crm.objects.deals.read
• Companies: crm.objects.companies.read
• Tickets: crm.objects.tickets.read

Grant: Read permission for object types you’ll search

---

​

Lookup HubSpot Object (V2)

Action: Get single contact, deal, company, or ticket Required scopes:

• Contacts: crm.objects.contacts.read
• Deals: crm.objects.deals.read
• Companies: crm.objects.companies.read
• Tickets: crm.objects.tickets.read

Grant: Read permission for object types you’ll lookup

---

​

Update HubSpot Object (V2)

Action: Modify contacts, deals, companies, or tickets Required scopes:

• Contacts: crm.objects.contacts.write
• Deals: crm.objects.deals.write
• Companies: crm.objects.companies.write
• Tickets: crm.objects.tickets.write

Grant: Write permission for object types you’ll update

---

​

Create HubSpot Object (V2)

Action: Create new contacts, deals, companies, or tickets Required scopes:

• Contacts: crm.objects.contacts.write
• Deals: crm.objects.deals.write
• Companies: crm.objects.companies.write
• Tickets: crm.objects.tickets.write

Grant: Write permission for object types you’ll create

---

​

Get Timeline Events (V2)

Action: Retrieve timeline events from records Required scopes:

• All object types: crm.objects.{object_type}.read
• Timeline events: timeline (if available on your HubSpot tier)

Example: To get contact timeline events:

• crm.objects.contacts.read

---

​

Create Timeline Event (V2)

Action: Log custom events to timelines Required scopes:

• Timeline events: timeline or crm.objects.timeline.write

Note: Timeline event creation may require specific HubSpot tier (Professional+)

---

​

Get Engagements (V2)

Action: Retrieve calls, emails, meetings, notes, tasks Required scopes:

• Engagements: crm.objects.{object_type}.read
• Plus: Object read permission

Example: To get deal engagements:

• crm.objects.deals.read
• Engagement access (usually included with object read)

---

​

Create Engagement (V2)

Action: Create calls, emails, meetings, notes, tasks Required scopes:

• Notes: crm.objects.notes.write
• Calls: crm.objects.calls.write
• Emails: crm.objects.emails.write
• Meetings: crm.objects.meetings.write
• Tasks: crm.objects.tasks.write

Plus: Read permission for associated objects (contact, deal, company)

---

​

Common Scope Combinations

​

Basic Contact Management

Use case: Search, view, update contacts Scopes needed:

• crm.objects.contacts.read
• crm.objects.contacts.write

---

​

Deal Pipeline Automation

Use case: Search deals, get timeline, update stages Scopes needed:

• crm.objects.deals.read
• crm.objects.deals.write
• crm.objects.contacts.read (for associated contacts)

---

​

Full Enrichment Workflow

Use case: Lookup contact, enrich, update, log timeline event Scopes needed:

• crm.objects.contacts.read
• crm.objects.contacts.write
• timeline or crm.objects.timeline.write

---

​

Customer Onboarding

Use case: Lookup deal, get engagements, create notes Scopes needed:

• crm.objects.deals.read
• crm.objects.contacts.read
• crm.objects.notes.write
• timeline (for timeline events)

---

​

Troubleshooting Scope Issues

​

”Insufficient Permissions” Error

Error: Action fails with permission error Causes:

1. Missing required scope
2. HubSpot user role doesn’t allow
3. Object type not available on your HubSpot tier

Fix:

1. Reconnect HubSpot with more scopes
2. Check HubSpot user permissions
3. Verify feature available on your plan

---

​

Can’t Grant Certain Scopes

Problem: Scope not appearing when connecting Causes:

1. HubSpot tier doesn’t include feature
2. Not a HubSpot admin
3. Scope deprecated or renamed

Fix:

1. Check HubSpot tier requirements
2. Ask admin to connect
3. Use updated scope name

---

​

Scope Works for One Object, Not Another

Problem: Can read contacts but not deals Cause: Only granted scope for one object type Fix:

1. Reconnect HubSpot
2. Grant scopes for all needed object types
3. Check each: contacts, deals, companies, tickets

---

​

Recommended Setup

​

For Most Workflows

Grant these scopes when connecting: Object access:

• ✅ Read contacts
• ✅ Write contacts
• ✅ Read companies
• ✅ Write companies
• ✅ Read deals
• ✅ Write deals

Engagement access:

• ✅ Read engagements (calls, emails, meetings, notes)
• ✅ Write notes
• ✅ Write tasks

Timeline:

• ✅ Timeline events (if available)

Why: Covers 90% of common workflows, avoids reconnecting later

---

​

Minimal Setup (Testing)

For initial testing only:

• Read contacts
• Write contacts

Limitation: Can only work with contacts, no deals/companies/engagements

---

​

HubSpot Tier Considerations

​

Free/Starter

Available:

• Basic object read/write (contacts, deals, companies)
• Basic engagements

Limited:

• Custom timeline events may not be available
• Some engagement types limited
• Advanced features restricted

---

​

Professional/Enterprise

Available:

• All object types
• All engagement types
• Custom timeline events
• Advanced features

Recommended: Grant all scopes for full functionality

---

​

Related Resources

Setup:

• HubSpot Setup Guide - Initial connection
• Authentication - How credentials work

Troubleshooting:

• Troubleshooting Guide - Permission errors
• Error Messages - Common errors

---

Last Updated: 2025-10-01