> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hubspot

> Learn how to connect Opal to Hubspot to manage access.

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 `1.1179.0` 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:

```
settings.billing.write (to remove users from paid roles)
settings.users.read
settings.users.teams.read
settings.users.teams.write (to add and remove users from teams)
settings.users.write
```

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.

> [!NOTE]
>
> 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.

| Field | Value |
| - | - |
| App name | A display name, for example `HubSpot` |
| App admin | The Opal owner responsible for this app |
| Description | Optional description shown in the catalog |
| Private app access token | The token from Step 1 |
| Visibility | Who 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

> [!NOTE]
>
> Provisioning requires the `settings.users.write` scope. To deprovision users
> who hold paid seats, also add `settings.billing.write`. See [Step
> 1](#1-create-a-legacy-app-in-hubspot).

Opal can automatically provision and deprovision users in HubSpot.

When provisioning is enabled, users who don't already have a HubSpot account are automatically created when they are granted access to a HubSpot team or role. If an account with the same email already exists, Opal uses it rather than creating a duplicate. HubSpot sends its welcome email only when **Send HubSpot welcome email to provisioned users** is turned on. Deprovisioning deletes users from HubSpot when you deprovision them manually, revoke their account in an access review, or when they're deprovisioned in your IdP or HRIS. Super Admins must be demoted in HubSpot before Opal can deprovision them.

This is configurable in **Setup > Edit > Provision HubSpot users** and **Deprovision HubSpot users**. For more details, see [User provisioning](https://docs.opal.dev/docs/user-provisioning.md).

## Teams

HubSpot teams are mapped to Opal Groups: membership syncs into Opal, and adding or removing members in Opal updates HubSpot.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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

> [accordion] A grant failed with 'User could not be matched with an account on HubSpot'
>
> 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.

> [accordion] Why don't I see any roles?
>
> 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.

> [accordion] How do I rotate the token?
>
> 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.

> [accordion] I changed a user's permissions in HubSpot but Opal doesn't show it.
>
> 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.

> [accordion] What data does Opal store?
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.