# Configure HubSpot user and permissions

To connect your HubSpot account to Commvault, you must configure a credential with the required permissions and provide the authentication details Commvault needs to connect.

## Create or identify a HubSpot credential

HubSpot uses service key authentication. A service key is a server-side integration that grants API access to a specific HubSpot portal through a long-lived access token.

To create a service key:

1. Sign in to the HubSpot portal.
2. Navigate to Development → Keys → Service Keys.
3. Click Create a Service Key.
4. Enter an app name for the Commvault integration (for example, "Commvault Backup").

5. Explicitly select all required scopes listed in the next section for the objects you intend to back up.

   Note

   Yellow and red caution icons denote sensitive and highly sensitive data scopes. You must grant these scopes if you want the corresponding data backed up.

6. Click Create.

7. Copy the generated token (starts with `pat-na1-` or `pat-eu1-` depending on your region). You will use this token as the Access Token (Service Key) when configuring the HubSpot application in Commvault. This token is shown only once — store it securely.
8. Record the Hub ID for the HubSpot account. You will use this ID as the Portal ID when configuring the Commvault credential.

## Assign the required permissions

The service key requires the following scopes. Grant all scopes listed below to ensure complete backup and restore coverage for HubSpot CRM, Marketing, Content, Sales, Commerce, Service, Automation, Data Management, and Reporting.

Operation | Required scopes | What they grant
--- | --- | ---
Browse and Backup — CRM Objects | `crm.objects.contacts.read` `crm.objects.companies.read` `crm.objects.deals.read` `crm.objects.quotes.read` `crm.objects.orders.read` `crm.objects.invoices.read` `crm.objects.owners.read` `crm.objects.leads.read` `crm.objects.appointments.read` `crm.objects.courses.read` `crm.objects.services.read` `crm.objects.listings.read` `crm.objects.projects.read` `crm.objects.custom.read` `crm.objects.commercepayments.read` `crm.objects.subscriptions.read` `crm.objects.feedback_submissions.read` `crm.objects.goals.read` `crm.objects.marketing_events.read` `crm.lists.read` | Read access to all CRM object types, including standard objects (contacts, companies, deals, tickets, leads, orders, projects, appointments, courses, services, listings), commerce objects (payments, subscriptions), feedback submissions, reporting goals, marketing events, and CRM lists (segments).
Backup — CRM Schemas | `crm.schemas.contacts.read` `crm.schemas.companies.read` `crm.schemas.deals.read` `crm.schemas.orders.read` `crm.schemas.projects.read` `crm.schemas.custom.read` `crm.schemas.commercepayments.read` `crm.schemas.subscriptions.read` | Read access to property definitions and custom object schemas for CRM entities.
Backup — Pipelines | `crm.pipelines.orders.read` | Read access to pipeline and stage definitions for deals, tickets, orders, leads, appointments, courses, services, listings, and projects.
Backup — Marketing and Content | `marketing-email` `marketing.campaigns.read` `forms` `content` `files` `hubdb` `business-intelligence` | Read access to marketing emails, campaigns, forms, CMS content (pages, blogs), File Manager files, HubDB tables, and reporting/analytics data.
Backup — Sales and Automation | `sales-email-read` `automation.sequences.read` `scheduler.meetings.meeting-link.read` | Read access to sales emails, automation sequences (also used in sales), and meeting link definitions.
Backup — Other | `tickets` `e-commerce` `conversations.read` `settings.users.read` `oauth` | Legacy scopes that cover ticket CRM objects, e-commerce line items and products, conversations, user settings, and OAuth metadata.
Restore — CRM Objects | `crm.objects.contacts.write` `crm.objects.companies.write` `crm.objects.deals.write` `crm.objects.invoices.write` `crm.objects.orders.write` `crm.objects.leads.write` `crm.objects.appointments.write` `crm.objects.courses.write` `crm.objects.services.write` `crm.objects.listings.write` `crm.objects.projects.write` `crm.objects.custom.write` `crm.objects.marketing_events.write` `crm.lists.write` | Write access to create and update CRM object records during restore.
Restore — CRM Schemas and Pipelines | `crm.schemas.contacts.write` `crm.schemas.companies.write` `crm.schemas.deals.write` `crm.schemas.projects.write` `crm.schemas.custom.write` `crm.pipelines.orders.write` | Write access to create and update property definitions, custom object schemas, and pipeline stage definitions during restore.
Restore — Marketing and Content | `marketing.campaigns.write` `content` `files` `forms` | Write access to create and update marketing campaigns, CMS content (pages, blogs, URL redirects), File Manager files, and forms during restore.
Restore — Automation | `automation` `automation.sequences.enrollments.write` | Write access to create and update automation workflows and sequence enrollments during restore.
Restore — Other | `conversations.write` `cms.membership.access_groups.write` `crm.import` `crm.export` | Write access to conversations, CMS membership access groups, and CRM import/export APIs used during restore.

## Provide connection details

During onboarding, Commvault requires two pieces of information:

- HubSpot Portal ID (stored as the credential username): The numeric portal identifier (for example, `12345678`). Find this in HubSpot Settings → Account → Integrations. The portal ID identifies which HubSpot account to back up and restore.
- HubSpot service key (stored as the credential password): The access token generated when you created the service key (starts with `pat-na1-` or `pat-eu1-`).

## Notes and considerations

- Token lifecycle: The service key access token does not expire automatically. However, if the token is revoked in HubSpot (for example, if the service key is deleted or regenerated), you must generate a new token and update the Commvault credential.
- Shared vs. dedicated credentials: Use a dedicated service key for Commvault backups rather than reusing an existing integration. This isolates backup operations from other integrations and makes it easier to audit and revoke access if needed.
- Scope inheritance: Some scopes grant broader access than their names suggest (for example, `content` grants read and write access to pages, blogs, HubDB, and URL redirects). Review the HubSpot API documentation to understand scope inheritance before limiting the granted scopes.

## Validate permissions

After creating the service key and granting the required scopes, run a test backup to confirm the credential is configured correctly.

If the backup fails with an error such as "Forbidden" or "Insufficient permissions," check the following:

- Verify that all required scopes listed above are granted in the service key's Scopes tab.
- Confirm that the access token is copied correctly into the Commvault credential password field (including the `pat-na1-` or `pat-eu1-` prefix).
- Verify that the portal ID is entered correctly as the credential username.
- Check that the service key has not been deleted or revoked in HubSpot.

×

Loading...