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

# HubSpot

## After this article

You will be able to connect HubSpot to Lumos to sync users, roles, and teams, track user activity and logins, and provision or deprovision HubSpot users from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User accounts |
| Roles | Permission | Yes | Yes | HubSpot roles (permission sets) |
| Teams | Permission | Yes | No | HubSpot teams |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Delete | User | Delete a user in HubSpot (requires the `settings.billing.write` scope) |

Lumos also tracks **last activity and last successful login** per user via HubSpot's audit-log and login-activity APIs (Enterprise tier required for audit logs).

## Required plan and roles

* **HubSpot plan:** the **Enterprise** version of HubSpot is required to connect this integration. Role management and audit-log-based activity tracking are Enterprise-tier features.
* **Authentication:** OAuth 2.0, you authorize Lumos through a HubSpot pop-up, so the connecting user must be able to install apps and grant the scopes below in the HubSpot account.
* **Full integration scopes:**
  * `oauth`, validate credentials
  * `settings.users.read`, list users and the roles associated with them
  * `settings.users.write`, assign/unassign roles, create and delete users
  * `settings.users.teams.read`, list team roles
  * `settings.users.teams.write`, assign/unassign roles
  * `settings.billing.write`, delete users (specifically required for user deletion)
  * `account-info.security.read`, get last login and last activity
  * `crm.objects.owners.read`, list accounts (owner records, including archived users)
* **Read-only scopes:** `oauth`, `settings.users.read`, `settings.users.teams.read`, `account-info.security.read`, `crm.objects.owners.read`. The `write` scopes are required if you want Lumos to manage access (create/delete users, assign/unassign roles), they are not optional for provisioning.

## Read-only access vs provisioning

**Is read-only possible?** Yes. HubSpot exposes a separate set of read scopes from the write scopes, so you can authorize the connection with only `oauth`, `settings.users.read`, `settings.users.teams.read`, `account-info.security.read`, and `crm.objects.owners.read` and get sync without provisioning.

**What read-only requires.** During the HubSpot OAuth pop-up, grant only the read-only scopes listed above rather than the full scope list, then follow the steps below to connect.

**What full provisioning requires.** The additional write scopes over read-only: `settings.users.write` to assign or unassign roles and create or delete users, `settings.users.teams.write` to assign or unassign team roles, and `settings.billing.write`, which is specifically required for user deletion.

**Watch out for.** The whole integration requires the HubSpot Enterprise tier, role management and activity tracking will not populate on lower tiers. If a user was authorized with only the read-only scopes and you later need provisioning, you'll need to reconnect and grant the write scopes, since HubSpot's OAuth authorization is scoped at connection time. User deletion specifically depends on `settings.billing.write`, if that scope was left out during authorization, deletions fail until you reconnect and grant it.

## Instructions

**Phase 1: Prepare HubSpot**

1. Confirm your HubSpot account is on the **Enterprise** tier.
2. Log in to HubSpot as a user who can authorize third-party app installs and grant the scopes listed above.

**Phase 2: Connect in Lumos**

1. Find the HubSpot card in your Lumos integrations (reconnect an existing card or add a new one).
2. Click **Connect**.
3. Follow the instructions in the HubSpot pop-up that appears to authorize Lumos and finish connecting.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection or authorization fails.** Confirm the account is on the HubSpot **Enterprise** tier and the authorizing user can install third-party apps and grant all requested scopes.

**User deletion fails.** Deleting users specifically requires the `settings.billing.write` scope. Reconnect the integration and make sure this scope is granted during the OAuth authorization.

**Role management or activity data missing.** Role management requires the Enterprise tier, and activity tracking depends on Enterprise-tier audit logs. On lower tiers these features will not populate.

**Assign role/entitlement fails with "No accounts found for the user" right after creating the user.** The target account must exist and be discovered by Lumos before an entitlement can be assigned. If a provisioning flow creates the account and immediately assigns a role, wait for the account to sync (or re-run the assignment step) so the newly created account can be found.