Skip to main content
With Opal’s integration with HubSpot, you can manage access to HubSpot users, teams, and roles (permission sets).
  • End users can request just-in-time, time-bound access to HubSpot roles and teams from Opal’s catalog, Slack, or the CLI.
  • Admins can grant and revoke access, provision and deprovision HubSpot users, and delegate approvals with full audit trails.
  • Auditors and security teams can run access reviews over HubSpot roles and team membership, and see every change as an event.

​
Requirements

  • You must be an Opal admin to set up the integration.
  • You need a HubSpot Super Admin to create the legacy app and its access token.
  • For self-hosted deployments, you must be on version [fill in exact release] or later.
  • Opal associates HubSpot users with Opal users through their primary email address.

​
1. Create a legacy app in HubSpot

In HubSpot, go to Settings > Integrations > Legacy Apps and select Create a legacy app. Give the app a name (for example, Opal). On the Scopes tab, add the following scopes:
These scopes let Opal read your users, teams, and roles, and (if enabled) provision users, manage team membership, and assign roles. If you only want read-only visibility and access reviews, you can omit settings.users.write. [Optionally] Add settings.billing.write if you want Opal to be able to deprovision users who hold paid seats. Without this scope, deprovisioning such a user fails with a clear error telling you to unassign the seat first.
These scopes cover HubSpot’s user and account settings only. Opal cannot read your CRM data — contacts, companies, deals, tickets, and marketing content are outside what this token can access.
Finally, select Create app and copy the access token.

​
2. Create the HubSpot app in Opal

In Opal, go to Inventory > +App and select the HubSpot tile.
FieldValue
App nameA display name, for example HubSpot
App adminThe Opal owner responsible for this app
DescriptionOptional description shown in the catalog
Private app access tokenThe token from Step 1
VisibilityWho can see this app in the catalog
Fill in the fields, then select Create. Opal validates the token and each scope immediately; results appear under the app’s Setup tab (App Validations), and you can re-run them there any time.

​
3. Import assets

After the first sync completes, select the app’s … menu > Import items to bring your HubSpot teams and roles into the Inventory. Your HubSpot users appear under the app’s Accounts tab automatically.

​
User provisioning

With provisioning enabled on the app, granting access to a person who doesn’t yet have a HubSpot account creates one for them (they receive HubSpot’s standard invite). If an account with the same email already exists, Opal uses it rather than creating a duplicate. With deprovisioning enabled, removing a user’s last access removes their HubSpot account. Provisioning and deprovisioning are both opt-in settings on the app’s edit page.

​
Teams

HubSpot teams are mapped to Opal Groups: membership syncs into Opal, and adding or removing members in Opal updates HubSpot.
HubSpot’s API has no way to remove a user from a single team. When Opal removes a team membership, it briefly clears the user’s team list and immediately rebuilds the remaining memberships. During that short window the user may appear team-less in HubSpot; the next sync reconciles any difference. We would recommend making team changes all in one place.
In order to deprovision a Super Admin from Opal, they must first be demoted in Hubspot.

​
Roles

HubSpot roles (permission sets) are available on** HubSpot Enterprise plans**. Two behaviors to know:
  • A HubSpot user holds one role at a time — assigning a role through Opal replaces the user’s existing role, matching how HubSpot’s own admin UI behaves.
  • Opal refuses any assignment that would demote your account’s last Super Admin. A HubSpot account with zero Super Admins cannot be recovered from the HubSpot UI, so Opal fails that request with a clear error instead. (Super Admin itself can’t be granted through the API — that always happens in HubSpot’s settings.)

​
FAQ

The person has no HubSpot account with their Opal primary email. Either create their HubSpot user (or enable provisioning on the app) or correct the email mismatch, then retry.
Roles require HubSpot Enterprise. Hubspot’s role API is not available on other plans. Opal takes this into consideration on connection and continues syncing users and teams normally.
Create a new token in HubSpot (Private Apps > your app > rotate), then paste it in the app’s Setup tab in Opal and re-run validations.
Opal tracks named permission sets. Editing a user’s individual permissions through HubSpot’s Edit access flow creates custom per-user permissions, not a permission set, and HubSpot’s API does not expose those — so they don’t appear in Opal. Use Assign permission set in HubSpot for changes you want reflected in Opal.
User IDs, names, and email addresses; team names and membership; role names and assignments — the minimum needed to show who has access to what. No CRM records are read or stored.
Last modified on July 14, 2026