Free tool
HubSpot API scope picker: find the minimum scopes for your integration
Tick the operations your integration needs and pick how it authenticates. You get the minimum scope list from HubSpot's reference, which scopes are tier-restricted or sensitive, and copy-ready output for a service key, an app-hsmeta.json file or an OAuth install URL.
Free, no sign-up. Data checked .
Runs in your browser. Nothing you tick leaves this page. Scope names checked against HubSpot's scopes reference on October 29, 2026.
Your scopes
Tick what the integration does. The list updates as you go. Without JavaScript, use the table below: it lists the scope HubSpot documents for every operation.
Every operation and its HubSpot scope
Availability is quoted from HubSpot's scopes reference. "Not documented" means HubSpot doesn't name a specific scope for that operation.
| Operation | Scope | Availability | Source |
|---|---|---|---|
| CRM records | |||
| Read contacts | crm.objects.contacts.read | All accounts | HubSpot |
| Create, update or delete contacts | crm.objects.contacts.write | All accounts | HubSpot |
| Read companies | crm.objects.companies.read | All accounts | HubSpot |
| Create, update or delete companies | crm.objects.companies.write | All accounts | HubSpot |
| Read deals | crm.objects.deals.read | All accounts | HubSpot |
| Create, update or delete deals | crm.objects.deals.write | All accounts | HubSpot |
| Read tickets | crm.objects.tickets.read | All accounts | HubSpot |
| Create, update or delete tickets | crm.objects.tickets.write | All accounts | HubSpot |
| Read custom object records | crm.objects.custom.read | Enterprise accounts only | HubSpot |
| Create, update or delete custom object records | crm.objects.custom.write | Enterprise accounts only | HubSpot |
| Import records (Imports API) | crm.import | All accounts | HubSpot |
| Export records (Exports API) | crm.export | All accounts | HubSpot |
| Properties and object definitions | |||
| Read contact property definitions | crm.schemas.contacts.read | All accounts | HubSpot |
| Create or edit contact properties | crm.schemas.contacts.write | All accounts | HubSpot |
| Read company property definitions | crm.schemas.companies.read | All accounts | HubSpot |
| Create or edit company properties | crm.schemas.companies.write | All accounts | HubSpot |
| Read deal property definitions | crm.schemas.deals.read | All accounts | HubSpot |
| Create or edit deal properties | crm.schemas.deals.write | All accounts | HubSpot |
| Read ticket property definitions | crm.schemas.tickets.read not in reference table | Not stated | HubSpot |
| Create or edit ticket properties | crm.schemas.tickets.write not in reference table | Not stated | HubSpot |
| Read custom object definitions (schemas) | crm.schemas.custom.read | Enterprise accounts only | HubSpot |
| Create or edit custom object definitions (schemas) | crm.schemas.custom.write not in reference table | Not stated | HubSpot |
| Pipelines, associations and lists | |||
| Read or edit deal and ticket pipelines and stages HubSpot's Pipelines guide lists one combined set of accepted scopes (object scopes such as crm.objects.deals.read, plus automation and others) and doesn't say which one each pipeline call needs. Only order pipelines have their own scopes. | not documented | – | HubSpot |
| Read order pipelines | crm.pipelines.orders.read | All accounts | HubSpot |
| Create or edit order pipelines | crm.pipelines.orders.write | All accounts | HubSpot |
| Read or create associations between records HubSpot has no association scope. Its Associate records guide lists the object scopes for every object type as accepted and doesn't say which ones each call checks, so pick the record scopes for the objects you associate. | not documented | – | HubSpot |
| Read lists (segments) | crm.lists.read | All accounts | HubSpot |
| Create, edit or delete lists | crm.lists.write | All accounts | HubSpot |
| Automation, forms and marketing email | |||
| Read, create or edit workflows (v4 Automation API) One scope covers reading and writing. Workflows that use Sensitive Data properties also need the matching sensitive scopes. | automation | Professional or Enterprise accounts only | HubSpot |
| Read, create or edit forms One scope covers the legacy and v3 Forms APIs, read and write. | forms | All accounts | HubSpot |
| Read, create or edit marketing emails The scopes reference says content covers the marketing email API. HubSpot's Marketing Email guide also accepts marketing-email (retrieve and send, all accounts) and transactional-email, without saying which each endpoint needs. Publishing needs Marketing Hub Enterprise or the transactional email add-on. | content | Content Hub (CMS Hub) or Marketing Hub Professional or Enterprise only | HubSpot |
| Files, CMS and HubDB | |||
| Read files in the file manager | files.read | All accounts | HubSpot |
| Upload or manage files | files.write | All accounts | HubSpot |
| Delete files | files.delete | All accounts | HubSpot |
| Read or edit website pages, landing pages and blog posts One scope covers pages, blog posts and marketing email, read and write. | content | Content Hub (CMS Hub) or Marketing Hub Professional or Enterprise only | HubSpot |
| Read HubDB tables and rows | hubdb.tables.read hubdb.rows.read | Content Hub (CMS Hub) or Marketing Hub Professional or Enterprise only | HubSpot |
| Edit HubDB tables and rows | hubdb.tables.write hubdb.rows.write | Content Hub (CMS Hub) or Marketing Hub Professional or Enterprise only | HubSpot |
| Publish or unpublish HubDB tables | hubdb.tables.publish | Content Hub (CMS Hub) or Marketing Hub Professional or Enterprise only | HubSpot |
| Owners, users and account | |||
| Read owners (users assigned to records) | crm.objects.owners.read | All accounts | HubSpot |
| Read users and their permissions | settings.users.read | All accounts | HubSpot |
| Create, edit or delete users and permissions | settings.users.write | All accounts | HubSpot |
| Read teams | settings.users.teams.read | All accounts | HubSpot |
| Assign users to teams | settings.users.teams.write | All accounts | HubSpot |
| Read account activity (audit) logs | account-info.security.read | All accounts | HubSpot |
| Webhooks, timeline events and conversations | |||
| Webhooks: contact events | crm.objects.contacts.read | All accounts | HubSpot |
| Webhooks: company events | crm.objects.companies.read | All accounts | HubSpot |
| Webhooks: deal events | crm.objects.deals.read | All accounts | HubSpot |
| Webhooks: ticket events HubSpot's webhooks table lists the legacy tickets scope for ticket events. Its granular-scopes guide maps tickets to crm.objects.tickets.read and .write; check your app's webhook settings, which prompt for the scope a subscription needs. | tickets legacy | All accounts | HubSpot |
| Webhooks: conversation events | conversations.read | All accounts | HubSpot |
| Read timeline events | timeline.read not in reference table | Not stated | HubSpot |
| Create timeline events on records HubSpot's timeline guide says events must be created with an OAuth access token; private app tokens and developer API keys can't. | timeline.write not in reference table | Not stated | HubSpot |
| Read inbox threads and messages | conversations.read | All accounts | HubSpot |
| Create or manage threads and messages | conversations.write | All accounts | HubSpot |
How HubSpot scopes work
A scope is a permission on a HubSpot credential. Most follow a pattern: crm.objects.<object>.read or .write for records, crm.schemas.<object>.read or .write for property definitions, plus feature scopes such as automation (workflows), forms, content (pages, blog posts and marketing email) and crm.lists.read. HubSpot’s API reference lists the scopes each endpoint accepts, and the scopes reference says which account tiers can grant each one. Scopes also depend on what the account has: HubSpot’s example is an account without HubDB, whose private apps don’t get the HubDB scope.
Three things catch people out:
- Read and write are separate scopes. HubSpot’s descriptions don’t say the contacts or deals write scopes include reading, so if an integration looks a record up before it updates it, request both.
- Sensitive Data needs its own scopes. In Enterprise accounts, values of properties marked Sensitive or Highly Sensitive need the matching
.sensitiveor.highly_sensitivescopes on top of the object scopes. Without them, a request that includes such a property returns 403. - Tokens ignore user permissions. HubSpot says an OAuth token reflects the scopes requested, not what the installing user can see. A user who sees only their own contacts can authorize an app that reads them all.
Service keys, OAuth apps and legacy private apps
As of October 29, 2026:
| Credential | Use it for | Scopes |
|---|---|---|
| Service key | REST API calls in your own account. No webhooks or UI extensions. | Required only; editable after creation |
| Project app, static auth | One account, with webhooks, cards or other app features | requiredScopes in app-hsmeta.json |
| Project app, OAuth | Several accounts (allowlist) or the Marketplace | Required, optional and conditionally required |
| Legacy private app | Existing integrations only | Edited on the app’s Scopes tab |
HubSpot disabled creation of new legacy private apps on September 28, 2026 for new accounts and October 26, 2026 for existing ones. Existing private apps keep working. On September 8, 2026 HubSpot also split the coarse tickets, files, hubdb and timeline scopes into granular ones, such as crm.objects.tickets.read, and offers an in-app migration for existing apps. More detail: can you still create a HubSpot private app.
For OAuth apps, put scopes that need a higher tier in optionalScopes. A required scope the account doesn’t have makes the install fail; an optional one is dropped and the app installs anyway.
Least privilege, then audit
Give each integration its own credential and only the scopes for what it does today. A leaked token can do whatever its scopes allow, and revoking a shared key breaks everything at once. Private apps, service keys and privately distributed apps also share the account’s daily API limit; see HubSpot API rate limits.
Review installed apps at least once a year: owner, purpose and scopes for each connected app, private app and service key. The steps are in how to audit connected apps and private apps. If an integration creates properties, crm.schemas.<object>.write is the scope; see creating a property with the API.
Where Jetstack AI fits
Jetstack AI connects to a portal through HubSpot’s OAuth flow from Client Accounts, and its HubSpot platform guide lists the scopes it requests. You can revoke it under Settings → Integrations → Connected Apps. The audit only reads your portal.
Jetstack’s own API, CLI and MCP server use jsai_ keys with their own scopes, such as portals:read, hubspot:browse and hubspot:deploy. The scopes that deploy Projects work or buy credits are never part of a preset. See authentication and scopes and the developer overview.
HubSpot API scope picker
Questions about this tool.
Which scopes does a HubSpot integration need at minimum?
One scope per object and action it actually uses: crm.objects.contacts.read to read contacts, crm.objects.contacts.write to change them, crm.schemas.contacts.write to create contact properties, and so on. HubSpot lists the accepted scopes for each endpoint on its API reference pages. Anything beyond that is access a leaked token could use.
What is the difference between required and optional scopes?
Required scopes must be in the scope parameter of the install URL, and the install fails if the account doesn't have access to one of them. Optional scopes go in optional_scope and are dropped when the account lacks the feature, for example an Enterprise-only scope in a Starter account. Only OAuth apps can use optional and conditionally required scopes; static auth apps and service keys take required scopes only.
Can I still create a HubSpot private app to get a token with these scopes?
No. HubSpot disabled creation of new legacy private apps on September 28, 2026 for new accounts and October 26, 2026 for existing accounts. Existing private apps keep working. For a new integration in your own account, create a service key, which takes the same object-specific scopes.
Sources
- Scopes reference (HubSpot Developers)
- App configuration: auth and scopes in app-hsmeta.json (HubSpot Developers)
- Working with OAuth: authorization URL parameters (HubSpot Developers)
- Sensitive Data scopes (HubSpot API reference)
- Update your app to use granular scopes (HubSpot Developers)
- Account service keys (HubSpot Developers)
- Legacy private app creation sunset (HubSpot Developer Changelog)
- Webhooks API: scopes per subscription type (HubSpot Developers)
- Authentication and scopes (Jetstack AI documentation)
HubSpot changes often. Spotted something out of date? Tell us at team@jetstack.ai.