HubSpot

HubSpot is a CRM platform for marketing, sales, and customer service teams. Connect your HubSpot account to Oleria to see every user, the teams and roles they hold, and the private apps, integrations, and keys that can act on the account. Oleria reads this data from the HubSpot API with a private app access token or with OAuth, so you can find dormant or over-privileged access and act on it directly from Oleria. Oleria reads access to the HubSpot account itself. It doesn’t import contacts, companies, deals, tickets, or other CRM records.

What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your HubSpot account:

Accounts - every user in the account, with their name, email address, status (active or deactivated), super admin flag, role, seats (shown as license type, and as paid or free), created date, and last activity from their latest login or audit log action. Where HubSpot’s security activity (or, on Enterprise plans, its audit log) has the evidence, Oleria also shows two-factor authentication and passkey enrollment, single sign-on (SSO) status, and the date of the user’s last password change.
Non-human identities - the private app or OAuth app the connection uses, with its credential and granted scopes, shown once together with that app’s own install and token events, plus the private apps, installed integrations, service keys, personal access keys, developer API keys, and SMTP tokens that appear in the account’s security activity. Each one shows whether it’s still active. Where HubSpot reports the user who created it, that user is marked as its owner.
Teams - every team and its members, with each membership marked as the user’s primary team or an additional team.
Roles - every role defined in the account, plus Super Admin, with each user’s role assignments. Users with no role are shown with Custom permissions.
Activity - successful and failed logins with IP address and location; security activity such as two-factor, passkey, password, and SSO changes, admin permission changes, user impersonation, team membership changes, exports, and the creation, rotation, viewing, and revocation of private app tokens and keys; and, on Enterprise plans, the full audit log.

Oleria refreshes this data on its regular sync schedule.

Prerequisites

A HubSpot Super Admin. Only a super admin can create a private app.
Admin access on the Oleria platform to add a new integration.

Users, teams, login history, and security activity are available on every HubSpot plan. Roles need a paid plan, and the audit log needs an Enterprise plan. On other plans, Oleria syncs without that data and shows no error.

Choose an authentication method

Method	When to use it
Private app access token (recommended)	The simplest setup: one token from a private app you create in HubSpot. It keeps existing HubSpot connections working, and it’s the only method that can assign roles that need a paid seat.
OAuth 2.0	Use it if your policy requires OAuth. You create an app with private distribution in your own HubSpot account with the HubSpot CLI, and Oleria connects through it.

The exact location of these settings can change over time. If the steps below don’t match what you see, refer to HubSpot’s private apps and OAuth documentation.

Set up a private app access token

Create a private app

Sign in to HubSpot as a super admin, go to Development -> Legacy apps, and create a private app. Name it Oleria.

Select the scopes

On the Scopes tab, select the read scopes in the first table below. To let Oleria take remediation actions, also select the write scopes in the second table.

Copy the access token

Create the app and copy its access token.

Treat the token like a password. Anyone who has it can act in HubSpot with the scopes you granted. Store it securely and rotate it per your organization’s security policy.

Read scopes, for discovery:

Scope	What it adds
`settings.users.read` (required)	Users, their roles, and the role catalog.
`settings.users.teams.read`	Teams and team membership.
`crm.objects.owners.read`	User status (active or deactivated) and each user’s created date.
`account-info.security.read`	Login history and security activity, which also supply non-human identities, last login, two-factor, SSO, and password evidence. On Enterprise plans, it also reads the audit log.

If you leave out an optional read scope, Oleria skips the data it unlocks and still syncs the rest. Write scopes, only if you want Oleria to take remediation actions:

Scope	What it allows
`settings.users.write`	Creating and removing users, and assigning and removing roles.
`settings.users.teams.write`	Adding users to teams, removing them from teams, and creating teams.
`settings.billing.write`	Assigning roles that need a paid seat. Select it only if you want Oleria to assign those roles.

Set up OAuth

HubSpot creates apps on its developer platform with the HubSpot CLI, not with a form in the HubSpot UI. The app’s redirect URLs and scopes live in its app-hsmeta.json file.

Create an app project

Install the HubSpot CLI, authenticate it to your HubSpot account, and run hs project create. Choose an App, private distribution, and OAuth authentication.

Set the redirect URLs and scopes

In the project’s app-hsmeta.json, set the auth block. Use your Oleria workspace URL (the one in your browser’s address bar) for both redirect URLs:

"auth": {
  "type": "oauth",
  "redirectUrls": [
    "https://acme.oleria.com/workspace/integrations/hubspot/connect",
    "https://acme.oleria.com/workspace/integrations/edit"
  ],
  "requiredScopes": [
    "oauth",
    "settings.users.read",
    "settings.users.teams.read",
    "crm.objects.owners.read",
    "account-info.security.read"
  ],
  "optionalScopes": [
    "settings.users.write",
    "settings.users.teams.write"
  ]
}

Keep both optional scopes in the file even if you don’t plan to use remediation actions. Oleria always requests them as optional scopes, and HubSpot rejects the install if a requested scope isn’t configured on the app. You decide whether to grant them when you approve access. HubSpot also rejects the connection if a redirect URL doesn’t match exactly: the first is used when you add the integration, the second when you reconnect or edit it. The Oleria connection form shows both URLs when you choose OAuth.

Upload the project

Run hs project upload to build and deploy the app to your HubSpot account.

Copy the client credentials

In HubSpot, open the project’s app and copy the Client ID and Client secret from its Auth tab.

Connect HubSpot to Oleria

Open the integration

Go to your Oleria workspace, select Integrations -> select HubSpot.

Complete the connection form

Choose the authentication method and provide the following:

Field	Notes
Authentication method	Private app access token (Recommended) or OAuth 2.0 (your own HubSpot app).
Private app access token	Private app method only. The access token you copied.
OAuth client ID	OAuth method only. From the app you created.
OAuth client secret	OAuth method only. From the app you created.
API base URL	Optional. Leave it empty to use `https://api.hubapi.com`, which serves every HubSpot data-hosting location. If you enter a URL, it must be an `https` URL on `hubapi.com` or one of its subdomains, with no port.

Authenticate

Select Authenticate. Oleria checks that the credential can read the account and its users before it saves the integration. With OAuth, you’re redirected to HubSpot to approve access, then back to Oleria automatically.

Verify the integration

Confirm the new instance appears on the Connected tab of your Oleria Integrations page with a status of Healthy. It’s named after your HubSpot account ID, for example HubSpot (12345678). After the first sync completes, you can review the discovered accounts, teams, roles, non-human identities, and activity in your Oleria workspace.

If you rotate the private app token in HubSpot, update it in Oleria by editing the integration. To keep the stored token or client secret when you edit other settings, leave that field empty. If you change the OAuth client ID, enter the new app’s client secret too.

Remediation actions

Beyond discovery, Oleria can act on HubSpot access to remediate risk. Remediation needs the write scopes described above. Oleria checks the scopes before an action runs and reports any that are missing. If HubSpot doesn’t report the token’s scopes, Oleria runs the action and reports HubSpot’s own permission error.

Action	What it does	Reversible?
Create user	Invites a user by email address and sends HubSpot’s welcome email. If a user with that email already exists, Oleria leaves it as is.	Yes - deletes the created user.
Delete user	Deletes the user from the account. HubSpot’s REST API can’t deactivate a user, so deleting is the only way Oleria can take access away.	Partly - creates the user again with the same email, name, role, and teams, without sending a welcome email. HubSpot gives the user a new ID, and their record ownership, history, seat, and Super Admin aren’t restored. Grant Super Admin again in HubSpot if needed.
Assign role	Sets the user’s role. A HubSpot user holds one assignable role, so this replaces the previous one.	Yes - restores the previous role, or clears the role if the user had none.
Remove role	Clears the user’s role. If the user holds the role only as an extra role that HubSpot’s API can’t change, the action fails, and you remove the role in HubSpot.	Yes - assigns the role again while the user still has no role.
Add to team	Adds the user to a team. The team becomes the user’s primary team if they don’t have one, and an additional team otherwise.	Yes - removes the same membership.
Remove from team	Removes the user from a team. Removing a user from their primary team leaves them with no primary team.	Yes - adds the same membership back. If the user was removed from their primary team and has been given another primary team since, Oleria leaves it as is.
Create team	Creates an empty team with the given name. If a team with that name already exists, Oleria leaves it as is.	Yes - deletes the team while it has no members.

A few safeguards apply:

Oleria won’t delete the user who created the private app the connection uses, or who installed the OAuth app, because that would break the connection. If HubSpot doesn’t say which user that is, Oleria won’t delete any super admin.
Oleria won’t delete the last super admin.
Oleria can’t grant or revoke Super Admin. HubSpot doesn’t allow it through the API, so change it in HubSpot.
Assigning a role that needs a paid seat requires settings.billing.write, which only a private app connection can use. Without it, Oleria reports the missing scope.
HubSpot plan limits still apply. For example, creating a user fails when no seat is available, and creating a team fails when the account has reached its team limit. Oleria reports HubSpot’s message.

Known limitations

Delete only, no deactivation. HubSpot’s REST provisioning API can’t deactivate or reactivate a user. Deactivation is available only through HubSpot’s SCIM API, which needs a Professional or Enterprise plan with single sign-on. Oleria doesn’t offer deactivate or reactivate actions, and offers Delete user as the leaver action instead.
User status needs the owners scope. The HubSpot users API doesn’t report whether a user is deactivated, so Oleria reads it from HubSpot’s CRM owner records. Without crm.objects.owners.read, every user shows as active.
Non-human identities can’t be disabled from Oleria, and sessions can’t be revoked. HubSpot has no API to deactivate or rotate private app tokens, service keys, personal access keys, developer API keys, or SMTP tokens, to uninstall another app, or to end a user’s sessions.
Non-human identity and authentication evidence is limited to HubSpot’s security activity. HubSpot has no API that lists private apps, installed integrations, or keys, or that reports a user’s two-factor enrollment, SSO status, or password changes. Oleria derives them from security activity events and, on Enterprise plans, from the matching audit log entries (HubSpot records some changes, such as password changes, only in the audit log), so it only sees what happened within the period HubSpot keeps that activity. An app or key with no recent events doesn’t appear, and users with no recent evidence show two-factor and SSO status as unavailable, not as disabled.
Roles and the audit log depend on your plan. Roles need a paid HubSpot plan, and the audit log needs an Enterprise plan. Login history covers the last 90 days.
Role permissions aren’t shown. HubSpot’s API lists roles and who holds them, but not the permissions each role grants.
No AI agents. HubSpot has no API that lists its AI agents, so Oleria doesn’t discover them.

Existing SCIM connections

If you connected HubSpot earlier with the SCIM setup, Oleria moves that connection to the native connector automatically. You don’t need to reconnect or trigger anything. The connection keeps its saved token, and its saved SCIM base URL (such as https://api.hubspot.com/scim/v2) is treated as the default API base URL. When you edit the integration, you can leave API base URL empty; the old SCIM URL isn’t used anymore. The SCIM setup’s token only grants user scopes, so after the move Oleria syncs users and roles but skips the data the other read scopes unlock, such as teams, user status, and activity. Actions work where HubSpot grants the token the needed scopes. If HubSpot won’t report a token’s scopes, Oleria still tries the action and reports HubSpot’s permission error. To get everything described on this page, edit the integration and enter a private app access token with the scopes above. The first sync after Oleria moves the connection re-creates your HubSpot accounts, and any groups the SCIM connection synced, with new IDs, because Oleria now uses HubSpot’s own user and team IDs instead of SCIM IDs. Access reviews that are already in progress and include HubSpot accounts keep pointing at the old accounts, so re-run or update them, along with any workflows that used the old accounts or groups. The Enable and Disable user actions are no longer available, because HubSpot’s REST provisioning API can’t deactivate a user. Use Delete user instead.

Contact us

For questions about this integration, contact us at support@oleria.com.

Overview

Generic connectors

Identity providers

HR systems

Cloud infrastructure

Applications

Ticketing

Messaging

What Oleria discovers

Prerequisites

Choose an authentication method

Set up a private app access token

Set up OAuth

Connect HubSpot to Oleria

Verify the integration

Remediation actions

Known limitations

Existing SCIM connections

Contact us

​What Oleria discovers

​Prerequisites

​Choose an authentication method

​Set up a private app access token

​Set up OAuth

​Connect HubSpot to Oleria

​Verify the integration

​Remediation actions

​Known limitations

​Existing SCIM connections

​Contact us

What Oleria discovers

Prerequisites

Choose an authentication method

Set up a private app access token

Set up OAuth

Connect HubSpot to Oleria

Verify the integration

Remediation actions

Known limitations

Existing SCIM connections

Contact us