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

# HubSpot authentication guide

export const m_runner = "Maia runner";

export const designer = "Designer";

export const maia = "Maia";

This is a step-by-step guide to acquiring HubSpot credentials and authorizing the [HubSpot Load](/docs/components/hubspot-load) and [HubSpot Query](/docs/components/hubspot-query) components.

{maia}'s HubSpot connectors can use OAuth or Private App Token for third-party authentication. This guide will only explain the Private App Token method. Read [OAuth](/docs/guides/oauth) for details of the OAuth method.

Authorizing either of these HubSpot connectors requires four steps:

1. [Obtain a Private App Token](#obtain-a-private-app-token) from the HubSpot portal.
2. [Create a secret](#create-a-secret) to store the Private App Token.
3. [Add a secret definition](/docs/guides/secrets-and-secret-definitions) to the **Your projects** menu.
4. Use the **Private App Token** property drop-down in the HubSpot Load or HubSpot Query component to select the secret holding the token you have created.

***

## Obtain a Private App Token

1. Open [HubSpot Accounts](https://app.hubspot.com/myaccounts-beta) in a browser and enter valid login credentials to continue.

2. On the **HubSpot Accounts** dashboard, click the name of the account you will use to obtain the token.

   <Note>
     * This must be an **app developer** account.
     * You may be asked to provide additional login credentials to open the account.
   </Note>

3. On the HubSpot Developer **Home** page, click **Manage apps**.

4. On the **Apps** page, click **Get HubSpot API key** in the top-right of the page.

5. In the **Developer App key** dialog, click **Show key**.

6. Copy the contents of the revealed **API key** field, as this HubSpot Private App Token will be required when creating the secret.

7. Close the dialog and exit the portal.

### Scopes

Your app must have certain scopes to collect data from HubSpot. Check that your app has the following scopes. If not, click the **Auth** tab for your app and then, in the **Scopes** section, click **Add new scope** to add each scope. For more information, read HubSpot's [Scopes](https://developers.hubspot.com/docs/guides/apps/authentication/scopes) documentation.

* crm.lists.read
* crm.lists.write
* crm.objects.companies.read
* crm.objects.companies.write
* crm.objects.contacts.read
* crm.objects.contacts.write
* crm.objects.deals.read
* crm.objects.deals.write
* crm.objects.owners.read
* crm.schemas.deals.read
* crm.schemas.deals.write
* crm.schemas.companies.read
* crm.schemas.companies.write
* crm.schemas.contacts.read
* crm.schemas.contacts.write

***

## Create a secret

You must create a secret to store your HubSpot Private App Token. How this secret is stored depends on your {maia} deployment model:

* In a [Full SaaS](/docs/guides/runner-overview#matillion-full-saas) deployment model, you must add a secret to the internal managed vault service that is hosted in Matillion's own AWS infrastructure. Read [Secrets and secret definitions](/docs/guides/secrets-and-secret-definitions#create-a-secret-definition-matillion-full-saas) for details.
* In a [Hybrid SaaS](/docs/guides/runner-overview#hybrid-saas) deployment model, you must add a secret to either [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) or [Azure Key Vault](https://learn.microsoft.com/en-us/azure/key-vault/secrets/about-secrets) in your own cloud infrastructure, as described below.
* In a Hybrid SaaS deployment model using the {m_runner} for Snowflake, read [Secrets in the {m_runner} for Snowflake](/docs/guides/snowflake-runner-secrets) for details of how to store the secret in a Snowflake schema.

### AWS Secrets Manager

1. Log in to the AWS account that houses your {m_runner}. This must be in the same AWS Region as the agent selected when the [project](/docs/guides/projects) was created.
2. In the search bar search for **Secrets Manager** to access the **Secrets** page.
3. Click **Store a new secret**.
4. Select **Other type of secret** and create a **Key/value** pair with the following details:
   * **Key:** Enter a label you will use to identify the token.
   * **Value:** Enter the HubSpot Private App Token code you copied earlier.
5. Click **Next** and on the next page enter a **Secret name**. This is the name that will appear in the [Secret definitions](/docs/guides/secrets-and-secret-definitions) list in **Your projects**.
6. The remainder of the details aren't needed, so click **Next** and **Next** again, then **Store** to complete the creation of the secret.

### Azure Key Vault

1. Log in to the Azure account that houses your {m_runner}. This must be in the same Azure Region as the agent selected when the [project](/docs/guides/projects) was created.
2. Click **Key vaults** and click the name of the key vault you want to reference. If there is only one, then this will be the **\[Default]** key vault configured in the agent.
3. Click **Objects** and then click **Secrets**.
4. Click **+ Generate/Import**.
5. On the **Create a secret** screen enter the following:
   * **Upload options:** Select **Manual**.
   * **Name:** Type a name for the secret. The secret name must be unique within a key vault. For more information on naming, read [Key Vault objects, identifiers, and versioning](https://learn.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates#objects-identifiers-and-versioning).
   * **Secret value:** Enter the HubSpot Private App Token code you copied earlier.
6. Click **Create**.

***

## Add a secret definition

Follow the steps in [Secrets and secret definitions](/docs/guides/secrets-and-secret-definitions).

***

## Return to Designer

1. Return to the HubSpot Query component in {designer}.
2. Click into the **Private App Token** property.
3. Select your new secret definition representing your HubSpot Private App Token.
4. Click **Save**.