Skip to main content

​
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

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

​
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.