Scopes

Scopes define what your app can do. You declare scopes when you create your app. Users grant these scopes during the OAuth flow.

Available scopes

Scope	Description
locations.readonly	View your locations and their settings
contacts.readonly	View your contacts, tags and notes
contacts.write	Create, edit and delete your contacts, tags and notes
opportunities.readonly	View your opportunities and their stages
opportunities.write	Create, edit and delete your opportunities and move them between stages
conversations.readonly	View your conversations and messages
conversations.write	Send, edit and delete messages in your conversations
calendars.readonly	View your calendars and events
calendars.write	Create, edit and delete your calendars and events
workflows.readonly	View your workflows and their steps
workflows.write	Create, edit and delete your workflows and their steps
media.readonly	View your files and media
media.write	Upload, edit and delete your files and media
webhooks.write	Create, edit and delete your webhook subscriptions

Requesting scopes

When you redirect the user to the authorization URL, include the scopes you need:

scope=contacts.readonly+contacts.write

The user sees a plain-English description of each scope on the consent screen.

Scope inheritance

If a user grants a write scope, they automatically have the corresponding readonly scope. For example:

• contacts.write implies contacts.readonly.
• opportunities.write implies opportunities.readonly.

You do not need to request both.

Webhook scopes

To subscribe to webhooks, your app needs the webhooks.write scope. However, the token must also have the read scope for the data in the webhook event.

For example:

• contact.created events require contacts.readonly.
• opportunity.created events require opportunities.readonly.
• conversation.created events require conversations.readonly.

A token with only webhooks.write cannot receive webhook events for data it cannot read through the API.

Changing scopes

If you need to add new scopes to your app:

1. Update the scopes in the developer portal.
2. If your app is published, it goes back to review. The same happens when you change the price, redirect URIs, webhook URL or billing setup.