# Hubspot

SureCloud connects to HubSpot to retrieve user and permission data, audit log records, and account-level security settings. This allows SureCloud to verify that access to customer and vendor data within HubSpot is appropriately controlled — confirming that users have the minimum necessary permissions, that audit logging is active, and that security settings such as two-factor authentication enforcement are configured correctly.

## Authentication and setup

HubSpot supports OAuth 2.0 for third-party integrations. SureCloud connects via the HubSpot OAuth flow using a private app token, which is HubSpot's recommended approach for server-side integrations.

{% stepper %}
{% step %}
**Create a Private App in HubSpot**

Log in to HubSpot with a Super Admin account. Navigate to **Settings → Integrations → Private Apps** and click **Create a Private App**. Name it `SureCloud CCM` and navigate to the **Scopes** tab.
{% endstep %}

{% step %}
**Configure required scopes**

Under **Scopes**, add the following read-only scopes: `crm.objects.contacts.read`, `settings.users.read`, `settings.users.teams.read`, and `audit-logs.read`. Click **Create App** and confirm.
{% endstep %}

{% step %}
**Copy the access token**

After creation, HubSpot will display the private app's **Access Token**. Copy it — it is not shown again in full after this point, though it can be rotated from the app settings page.
{% endstep %}

{% step %}
**Enter the token in SureCloud**

Navigate to **SureCloud → Integrations → HubSpot → Connect**. Paste the access token and click **Save**. Click **Test Connection** to confirm access.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the private app access token securely. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **HubSpot → Settings → Integrations → Private Apps → \[App Name] → Rotate Token** and update it in **SureCloud → Integrations → HubSpot → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                                        | Use Case                                                                        |
| ----------------------------------------------- | ------------------------------------------------------------------------------- |
| `GET /settings/v3/users`                        | Enumerate HubSpot users and their role assignments                              |
| `GET /settings/v3/users/{userId}/roles`         | Retrieve role assignments for individual users                                  |
| `GET /settings/v3/teams`                        | List teams and their membership for access scope evidence                       |
| `GET /account-info/v3/details`                  | Retrieve account details including two-factor authentication enforcement status |
| `GET /account-info/v3/activity-log/v1/activity` | Retrieve account-level audit log events for administrative activity evidence    |

## Pagination

`GET /settings/v3/users` uses cursor-based pagination. SureCloud uses the `paging.next.after` value from each response as the `after` parameter in the next request, continuing until no `paging.next` object is returned.

```json
GET /settings/v3/users?limit=100&after=<value_from_previous_response>
```

`GET /account-info/v3/activity-log/v1/activity` uses a similar `after` cursor. `GET /settings/v3/teams` and `GET /account-info/v3/details` return complete data in a single response.

## Required permissions / scopes

SureCloud requires a HubSpot private app with the following scopes:

| Scope                        | Purpose                                                  |
| ---------------------------- | -------------------------------------------------------- |
| `settings.users.read`        | Enumerate users and their role assignments               |
| `settings.users.teams.read`  | Read team membership and structure                       |
| `audit-logs.read`            | Access account-level audit log events                    |
| `account-info.security.read` | Read account security settings including 2FA enforcement |

No write, contact management, or marketing permissions are required.

## Polling frequency

| Data Type                  | Interval       |
| -------------------------- | -------------- |
| Users and role assignments | Every 24 hours |
| Team membership            | Every 24 hours |
| Audit log events           | Every 6 hours  |
| Account security settings  | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The private app access token is invalid or has been rotated without updating SureCloud. Navigate to **HubSpot → Settings → Integrations → Private Apps**, confirm the app is active, and rotate the token if necessary. Update it in **SureCloud → Integrations → HubSpot → Edit Connection**.

</details>

<details>

<summary>Audit logs are empty or returning 403 Forbidden</summary>

The `audit-logs.read` scope may not have been included when the private app was created. HubSpot does not allow scopes to be added to an existing private app — you must create a new private app with the correct scopes. Delete the existing app, create a new one with all required scopes, and update the token in SureCloud.

</details>

<details>

<summary>User list does not reflect all HubSpot users</summary>

`GET /settings/v3/users` requires the `settings.users.read` scope and a Super Admin token. If the private app was created by a non-Super Admin account, some user records may be restricted. Confirm the private app was created by a Super Admin and that the scope is correctly assigned.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/hubspot.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.