OAuth Scopes & Permissions

HubSpot Deploy uses OAuth scopes to control what operations the application can perform on your HubSpot portal. Understanding scopes is essential for successful deployments and avoiding permission errors.

What are Scopes?

Scopes are permissions that define what data and operations HubSpot Deploy can access in your portal. When you connect a HubSpot portal via OAuth, you select which scopes to grant.

For example:

• crm.schemas.custom.read — Read custom object schemas
• crm.schemas.custom.write — Create or modify custom object schemas
• automation.workflows.read — Read workflows
• automation.workflows.write — Create or modify workflows

tip

Scopes follow a read/write pattern: you need the read scope to fetch metadata and the write scope to deploy changes.

---

How Scopes Work in HubSpot Deploy

1. Scope Selection During Connection

When connecting a HubSpot portal via OAuth, you can select which permissions to request:

1. Click Connect HubSpot → OAuth tab
2. Review the Select Permissions section
3. Check the scopes you need for your use case
4. Click Connect with OAuth
5. HubSpot will show an authorization screen where you approve the requested scopes

2. Asked vs. Granted Scopes

HubSpot Deploy tracks two sets of scopes:

Type	Description
Asked Scopes	The scopes you requested during authorization
Granted Scopes	The scopes actually approved by the portal administrator

Important

A HubSpot administrator can deny some of the requested scopes during authorization. If this happens, you'll see a warning in the Instance dashboard.

3. Viewing Your Scopes

To see which scopes are active for a connection:

1. Go to Connections → Select your HubSpot portal
2. Look for the "Some permissions were denied" warning (if applicable)
3. Click View Scopes to see the full list of granted and denied scopes

---

Scope Requirements by Metadata Type

Different metadata types require different scopes for read and write operations:

CRM Objects & Schemas

Metadata Type	Read Scopes	Write Scopes
Custom Objects	crm.objects.custom.read crm.schemas.custom.read	crm.objects.custom.write crm.schemas.custom.write
Standard Objects (Contacts, Deals, etc.)	crm.schemas.contacts.read	crm.schemas.contacts.write
Pipelines	crm.objects.contacts.read	crm.objects.contacts.write
Property Groups	crm.schemas.contacts.read	crm.schemas.contacts.write
Association Definitions	crm.objects.custom.read crm.objects.contacts.read	crm.objects.custom.write crm.objects.contacts.write

Marketing & Content

Metadata Type	Read Scopes	Write Scopes
Forms	forms	forms
Email Templates	content	content
Landing Pages	content	content
Site Pages	content	content
Blog Posts	content	content
CTAs	content	content
Campaigns	marketing.campaigns.read	marketing.campaigns.write

Automation & Sales

Metadata Type	Read Scopes	Write Scopes
Workflows	automation.workflows.read	automation.workflows.write
Lists	crm.lists.read	crm.lists.write
Sequences	sales-email-read	(Read-only via API)

Other

Metadata Type	Read Scopes	Write Scopes
Owners	crm.objects.owners.read	(Read-only in HubSpot)
Quote Templates	crm.objects.quotes.read	crm.objects.quotes.write

---

Scope Impact on Deployments

Deployment Restrictions

When you create a deployment, HubSpot Deploy checks your granted scopes:

• ✅ Items with sufficient permissions — Can be deployed
• ⚠️ Items without write permissions — Cannot be deployed (checkbox disabled)
• 📋 Items with read-only scopes — Can be backed up and compared, but not deployed

Visual Indicators

In the comparison view:

Indicator	Meaning
Enabled checkbox	You have write permission for this item
Disabled checkbox (grayed out)	Missing write permission
Hover tooltip	Shows which scopes are missing

Example: Missing Workflow Write Permission

If you granted automation.workflows.read but not automation.workflows.write:

• ✅ You can backup workflows to Git
• ✅ You can compare workflows between portals
• ❌ You cannot deploy workflow changes

The workflow items will appear in comparisons with disabled checkboxes and a tooltip showing:

Missing Permissions:
automation.workflows.write

Reconnect with additional permissions to deploy this item.

---

Common Scope Scenarios

Scenario 1: Read-Only Access

Use Case: You want to backup metadata to Git but never deploy changes.

Recommended Scopes:

• oauth (required)
• crm.objects.custom.read
• crm.schemas.custom.read
• crm.schemas.contacts.read
• automation.workflows.read
• forms
• content

Result: You can create backups and comparisons, but all deployment checkboxes will be disabled.

---

Scenario 2: Full Deployment Access

Use Case: You want to deploy all metadata types between portals.

Recommended Scopes:

• oauth (required)
• crm.objects.custom.read + crm.objects.custom.write
• crm.schemas.custom.read + crm.schemas.custom.write
• crm.schemas.contacts.read + crm.schemas.contacts.write
• crm.objects.contacts.read + crm.objects.contacts.write
• automation.workflows.read + automation.workflows.write
• forms
• content
• crm.lists.read + crm.lists.write

Result: You can deploy all supported metadata types.

---

Scenario 3: Partial Permissions (Denied Scopes)

What Happened: You requested write scopes, but the HubSpot admin only granted read scopes.

Example:

• Asked: automation.workflows.read, automation.workflows.write
• Granted: automation.workflows.read (write was denied)

Result:

• ⚠️ Warning appears in Instance dashboard: "Some permissions were denied"
• Workflow items cannot be deployed
• You can still backup and compare workflows

Resolution:

1. Contact your HubSpot portal administrator
2. Request approval for the missing write scopes
3. Reconnect the portal with the same scopes
4. The admin approves the additional permissions

---

OAuth vs. Private App Tokens

HubSpot Deploy supports two authentication methods:

Feature	OAuth	Private App Token
Scope Selection	Choose scopes during connection	All scopes granted by token
User Approval	Requires admin approval	Created by admin directly
Granular Control	Yes — select only needed scopes	No — token has all configured scopes
Best For	Team environments with approval workflows	Personal use or full-access scenarios

When to Use Private App Tokens

If you need full deployment access and don't want to deal with OAuth scope approvals, use a Private App Token instead:

1. Go to HubSpot Settings → Integrations → Private Apps
2. Create a new private app
3. Grant all necessary scopes (e.g., crm.schemas.custom.write)
4. Copy the access token
5. In HubSpot Deploy, use Connect HubSpot → Private App Token tab

---

Troubleshooting Scope Issues

"Missing Permissions" Tooltip on Deployment Items

Cause: You don't have the required write scope for that metadata type.

Solution:

1. Click View Scopes in the Instance dashboard
2. Check which scopes are denied
3. Reconnect the portal and request the missing scopes
4. Ensure the HubSpot admin approves them during authorization

---

"Some permissions were denied" Warning

Cause: The HubSpot admin denied some of the scopes you requested.

Solution:

1. Click View Scopes to see which scopes were denied
2. Contact your HubSpot admin to discuss why they were denied
3. If approved, reconnect the portal to re-request the scopes

---

Deployment Fails with "Insufficient Permissions" Error

Cause: The scope was granted initially but later revoked in HubSpot.

Solution:

1. Go to HubSpot Settings → Integrations → Connected Apps
2. Find "HubSpot Deploy" and check the granted scopes
3. If scopes are missing, reconnect the portal in HubSpot Deploy

---

Can't Deploy Custom Objects

Cause: Missing crm.schemas.custom.write scope.

Solution:

• OAuth: Reconnect and select crm.schemas.custom.write in the scope selection UI
• Private App: Ensure your private app token has crm.schemas.custom.write enabled

---

Best Practices

1. Request Only What You Need

Don't request all scopes by default. Select only the scopes required for your use case:

• Backup-only: Request read scopes
• Deployment: Request both read and write scopes
• Specific metadata: Request scopes only for the types you'll use

2. Document Your Scope Requirements

If you're setting up HubSpot Deploy for a team, document which scopes are needed and why. This helps admins understand what to approve.

3. Use Private App Tokens for Automation

For CI/CD pipelines or automated deployments, use Private App Tokens instead of OAuth. This avoids scope approval workflows and ensures consistent access.

4. Regularly Review Granted Scopes

Periodically check your granted scopes to ensure they haven't been revoked:

1. Go to Connections → Select portal
2. Click View Scopes
3. Verify all required scopes are still granted

5. Test Deployments in Sandbox First

Before deploying to production, test in a sandbox portal to ensure your scopes are sufficient. This prevents deployment failures in critical environments.

---

Security Considerations

Principle of Least Privilege

Grant only the minimum scopes required for your use case. For example:

• If you only backup workflows, don't grant crm.schemas.custom.write
• If you never deploy forms, don't grant the forms scope

Scope Revocation

HubSpot admins can revoke scopes at any time:

1. Go to HubSpot Settings → Integrations → Connected Apps
2. Find "HubSpot Deploy"
3. Click Edit scopes or Revoke access

If scopes are revoked, HubSpot Deploy will show errors during backups or deployments.

Audit Trail

HubSpot Deploy tracks which scopes were asked and granted for each connection. This provides an audit trail for compliance and security reviews.

---

Related Features

• Connections - How to connect HubSpot portals
• Deployments - How scopes affect deployment capabilities
• Permissions - Workspace-level permissions (separate from OAuth scopes)