Scopes

Scopes are the permissions attached to your token. Each endpoint requires one or more scopes; if your token doesn’t have the scope an endpoint needs, the request is rejected with 401 Unauthorized or 403 Forbidden. Grant the minimum scopes your integration actually uses.

• Private Integration Tokens: you pick the scopes when you create the token. You can change them later without a new token: editing the integration keeps the existing token working.
• OAuth: you request scopes during authorization, and the user approves them. See OAuth.

Most resources have a *.readonly scope for reading and a *.write scope for creating, updating, and deleting. A few add extra scopes, such as pipelines.create for creating pipelines and payments/orders.collectPayment for recording a payment on an order.

The definitive list is in your account

The exact scopes available to you are shown when you create a Private Integration Token and on the OAuth consent screen, and can depend on your account. The names below match the v3 API.

Contacts

Scope	Grants
contacts.readonly	Read and look up contacts, notes, and tasks
contacts.write	Create/update/upsert/delete contacts, tags on contacts, notes, tasks, followers, and workflow/campaign enrollment

Conversations & messages

Scope	Grants
conversations.readonly	Read conversations
conversations.write	Create/update/delete conversations
conversations/message.readonly	Read and export messages
conversations/message.write	Send messages, record inbound messages and outbound calls, and manage message attachments
files.readonly	Download secure message attachments

Calendars & appointments

Scope	Grants
calendars.readonly	Read calendars, free slots, schedules, and services
calendars.write	Create/update/delete calendars, schedules, and services
calendars/events.readonly	Read appointments, events, appointment notes, calendar notifications, blocked slots, and service bookings
calendars/events.write	Book/update/delete appointments, events, appointment notes, calendar notifications, blocked slots, and service bookings
calendars/groups.readonly / calendars/groups.write	Read / manage calendar groups
calendars/resources.readonly / calendars/resources.write	Legacy: covers the deprecated bookable-resource endpoints. For new work, use the services and bookings endpoints, which use calendars.* and calendars/events.*

Opportunities

Scope	Grants
opportunities.readonly	Read opportunities and lost reasons, and list pipelines
opportunities.write	Create/update/upsert/delete opportunities, update status, and manage followers
pipelines.readonly	Read a single pipeline and its stages by ID
pipelines.create	Create pipelines
pipelines.write	Update or delete pipelines (stages are replaced as a whole on update)

Listing pipelines needs only opportunities.readonly. Fetching one pipeline by ID needs pipelines.readonly, so a token with only opportunities.readonly can’t read a single pipeline.

Custom fields, values & tags

Scope	Grants
locations/customFields.readonly / locations/customFields.write	Read / manage custom fields
locations/customValues.readonly / locations/customValues.write	Read / manage custom values
locations/tags.readonly / locations/tags.write	Read / manage tags

Custom objects & associations

Scope	Grants
objects/schema.readonly / objects/schema.write	Read / update custom object schemas
objects/record.readonly / objects/record.write	Read and search records / create, update, and delete records
associations.readonly / associations.write	Read / manage associations between objects
associations/relation.readonly / associations/relation.write	Read / manage relations between records

Your account/location

Scope	Grants
locations.readonly	Read your account/location details, timezones, and conversation channel providers
locations/templates.readonly	Read saved SMS/email templates
locations/tasks.readonly	Read account-level tasks
recurring-tasks.readonly / recurring-tasks.write	Read / manage recurring tasks

Users

Scope	Grants
users.readonly	Search and read users (team members)
users.write	Create, update, and delete users

Forms, funnels & surveys

Scope	Grants
forms.readonly / forms.write	Read forms and submissions / upload files to a contact’s custom fields
funnels/funnel.readonly	List funnels
funnels/page.readonly	List funnel pages
funnels/pagecount.readonly	Count funnel pages
funnels/redirect.readonly / funnels/redirect.write	Read / manage funnel redirects
surveys.readonly	Read surveys and submissions

Email

Scope	Grants
emails/templates.readonly / emails/templates.write	Read / manage email templates
emails/campaigns.readonly / emails/campaigns.write	Read / manage email campaigns
emails/stats.readonly	Read email statistics

Workflows & campaigns

Scope	Grants
workflows.readonly	List workflows (enroll contacts via the contacts.write scope)
campaigns.readonly	List campaigns (enroll contacts via the contacts.write scope)

Blogs

Scope	Grants
blogs/list.readonly	List blog sites
blogs/posts.readonly	Read blog posts, including a single post by ID
blogs/post.write	Create blog posts
blogs/post-update.write	Update blog posts
blogs/author.readonly	Read blog authors
blogs/category.readonly	Read blog categories
blogs/check-slug.readonly	Check whether a post slug is available

Social Planner

Scope	Grants
socialplanner/account.readonly / socialplanner/account.write	Read connected social accounts / disconnect them
socialplanner/oauth.readonly / socialplanner/oauth.write	Start and finish connecting a social account
socialplanner/post.readonly / socialplanner/post.write	Read / manage social posts (including bulk delete)
socialplanner/category.readonly	Read post categories and category queues
socialplanner/category.write	Create and edit category queues and manage their items
socialplanner/comments.readonly / socialplanner/comments.write	Read comments / reply to, like, and unlike comments
socialplanner/statistics.readonly	Read post statistics
socialplanner/tag.readonly	Read social post tags (list tags, tag details)
socialplanner/csv.readonly / socialplanner/csv.write	Read CSV bulk-upload jobs / bulk-upload posts by CSV and manage CSV imports
socialplanner/watermarks.readonly / socialplanner/watermarks.write	Read / manage image watermark templates for social posts, and apply them to images

Products & payments

Scope	Grants
products.readonly / products.write	Read / manage products, product reviews, and store product status
products/prices.readonly / products/prices.write	Read / manage product prices and inventory
products/collection.readonly / products/collection.write	Read / manage product collections
payments/orders.readonly / payments/orders.write	Read / manage orders
payments/orders.collectPayment	Record a payment against an order
payments/transactions.readonly	Read transactions
payments/subscriptions.readonly	Read subscriptions
payments/coupons.readonly / payments/coupons.write	Read / manage coupons

Invoices & estimates

Scope	Grants
invoices.readonly / invoices.write	Read invoices and invoice settings / create, update, send, and void invoices, record payments, and create text2pay invoices
invoices/estimate.readonly / invoices/estimate.write	Read / manage estimates
invoices/schedule.readonly / invoices/schedule.write	Read / manage recurring invoice schedules
invoices/template.readonly / invoices/template.write	Read / manage invoice templates

Tip

Getting 401 Unauthorized or 403 Forbidden on an endpoint? Check that the token has the scope that endpoint needs. For a Private Integration, edit the integration and add the scope; the existing token keeps working. For OAuth, re-authorize the grant with the extra scope. See Errors & Troubleshooting.