# Authentication

Step-by-step guide for connecting HubSpot to Tray.io

## Overview

The HubSpot connector uses **OAuth 2.0** authentication to securely connect your HubSpot account to Tray.io. This guide walks you through the complete authentication process, from adding the connector to your workflow to completing the OAuth authorization flow.

## Prerequisites

Before you begin, ensure you have:

* An active Tray.io account with workflow access
* A HubSpot account with appropriate permissions
* **Super Admin** or **App Marketplace access** permissions in HubSpot (required to authorize apps)

***

## Setup Guide: Connecting HubSpot to Tray.io

### Step 1: Add HubSpot Connector to Your Workflow

1. Navigate to your Tray.io workflow in the workflow builder
2. Click the **plus sign** (+) after any step in your workflow (or after the trigger if starting a new workflow)
3. Search for "HubSpot" in the connector search dialog
4. Select the **HubSpot connector** from the search results

![Adding HubSpot connector via the Add a step dialog](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step1-add-connector.png)

> **Info:** You can add the HubSpot connector at any step in your workflow. It doesn't need to be the first step unless you're using it as a trigger.

### Step 2: Open Authentication Setup

1. Click on the **HubSpot connector step** you just added to display the properties panel on the right
2. Select the **Authentication** tab in the properties panel
3. Click the **Create new authentication** button

![Authentication tab showing the Create new authentication button](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step2-auth-tab.png)

### Step 3: Name Your Authentication

The Tray.io authentication modal will appear.

1. **Name your authentication** in a way that will quickly identify it within your list of authentications
   * Examples: "HubSpot Production", "HubSpot Sandbox", "HubSpot - Marketing Account"
2. **Choose authentication visibility:**
   * **Personal**: Only you can use this authentication
   * **Organizational**: Others in your organization can use this authentication
3. Click **Next Step** to continue

![New authentication modal showing name and visibility fields](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step3-name-auth.png)

> **Tip:** Use descriptive names for your authentications, especially if you manage multiple HubSpot accounts (e.g., production, sandbox, or different team accounts).

### Step 4: Choose OAuth App (Tray's or Your Own)

You have two options for OAuth authentication:

#### Option A: Use Tray's OAuth App (Recommended for Most Users)

By default, the authentication will use **Tray's OAuth application**. This is the quickest and easiest option — no changes needed, simply proceed to **Step 5** to select scopes.

#### Option B: Use Your Own OAuth App (For Custom Requirements)

If you need custom OAuth apps for white-labeling or specific requirements, select **"Use own OAuth app"**.

1. Click the **Use own OAuth app** button

![OAuth configuration screen showing the Use own OAuth app button to click](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step4-oauth-config.png)

2. Enter your OAuth app details:
   * **App Name**: Name for your custom OAuth app
   * **App Description**: Brief description
   * **App Key**: Your HubSpot app's **Client ID**
   * **App Secret**: Your HubSpot app's **Client Secret**
3. Proceed to **Step 5** to select scopes

![New authorization app modal — entering app name and description](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step4b-custom-oauth-name.png)

![New authorization app modal — entering App Secret and App Key](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step4b-custom-oauth-credentials.png)

4. Click **Create authentication** to save the custom OAuth app

Once saved, you will be taken back to the authentication screen where the **Authorization app** dropdown will now show your custom app with a **Custom OAuth app** badge instead of Tray's default.

![Authentication screen showing the custom OAuth app selected in the Authorization app dropdown](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step4b-custom-oauth-selected.png)

> **Info:** To get your **Client ID** and **Client Secret**, navigate to your HubSpot app in the HubSpot Developer Portal, then go to the **Auth** tab. For detailed instructions on creating custom OAuth apps, see [Notes for Custom Service Environment usage](https://tray.ai/documentation/connectors/service/hubspot/notes-for-custom-service-environment/).

> **Warning:** **OAuth 2: IMPORTANT NOTE**The following operations **do not work with Public Applications** (including Tray's OAuth app):- Create object schema
> - Delete object schema
> - Update object schemaFor these operations, you must use your own private OAuth app. See HubSpot's [Private vs Public applications](https://developers.hubspot.com/docs/guides/apps/private-apps/overview) documentation for more information.

### Step 5: Select Required Scopes

Scopes determine what data and actions the HubSpot connector can access in your HubSpot account.

1. Review the **available scopes** in the authentication modal
2. **Select the scopes** required for your integration:
   * Check boxes for the scopes your workflow needs
   * Only select scopes you actually require (principle of least privilege)
3. Common scopes include:
   * `crm.objects.contacts.read` - Read contacts
   * `crm.objects.contacts.write` - Create/update contacts
   * `crm.objects.companies.read` - Read companies
   * `crm.objects.deals.read` - Read deals
4. Click **Create authentication** once you have selected your scopes

> **Info:** **Scope Selection Note**: If you're using an authentication created before July 31st 2022, please see our [Scopes documentation](https://tray.ai/documentation/connectors/service/hubspot/notes-on-using-hubspot/#scopes-cont) for important updates about deprecated scopes.

> **Tip:** Not sure which scopes you need? Start with read-only scopes and add write scopes only when your workflow requires them. You can always update authentication scopes later.

### Step 6: Complete OAuth Authorization in HubSpot

After configuring scopes, you'll authorize Tray to access your HubSpot account.

1. Click the **Create authentication** button
2. You'll be **redirected to HubSpot** in a new window/tab
3. **Log in to your HubSpot account** (if not already logged in)
4. **Select the HubSpot account** you want to connect (if you have access to multiple accounts)
5. **Review the permissions** that Tray is requesting (these match the scopes you selected)
6. Click **Grant access** or **Authorize** to approve the connection

![HubSpot OAuth authorization page — sign in or create a HubSpot account](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step6-hubspot-signin.png)

![Selecting the HubSpot account to connect to Tray.io](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step6-hubspot-account-select.png)

> **Warning:** You must have **Super Admin** or **App Marketplace access** permissions in HubSpot to authorize the connection. If you don't have these permissions, contact your HubSpot administrator.

### Step 7: Confirm Successful Connection

After authorization, you'll be redirected back to Tray.io.

1. The authentication modal will close automatically
2. Your **new authentication** will appear in the Authentication dropdown in the properties panel
3. It will be **automatically selected** for the current connector step

> **Check:** **Authentication Complete!** Your HubSpot connector is now authenticated and ready to use.

### Step 8: Test Your Connection

It's important to verify your authentication is working correctly.

1. In your HubSpot connector step, select an **operation** from the dropdown (e.g., "List contacts")
2. Configure any required fields for the operation
3. Click the **Test step** button or **Run workflow** to test the connection
4. Check the **Debug panel** to verify you're receiving data from HubSpot

![Testing the HubSpot connection with a List contacts operation](https://tray.ai/documentation/images/connectors/service/hubspot/auth-step8-test-connection.png)

> **Info:** If you encounter errors during testing, verify:- Your authentication is selected in the Authentication dropdown
> - You've selected the appropriate scopes for the operation you're testing
> - Your HubSpot account has data available (e.g., contacts exist if testing "List contacts")

***

## Uninstallation & Disconnection Guide

This section covers how to disconnect HubSpot from Tray.io, whether you need to remove the connector from a workflow or completely revoke access.

### Removing HubSpot Connector from a Workflow

To remove a HubSpot connector step from your workflow:

1. Open the **workflow** containing the HubSpot connector
2. **Hover over** the HubSpot connector step you want to remove
3. A **trash icon** will appear
4. Click the **trash icon** to delete the step
5. Confirm deletion if prompted

![Hovering over a connector step reveals the delete (trash) icon](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-remove-step.png)

> **Info:** Removing a connector step from a workflow does **not** delete the authentication. Other workflows using the same authentication will continue to work.

### Disconnecting HubSpot Authentication in Tray

To disconnect an authentication without deleting workflows:

#### Option 1: Remove from Specific Workflow Step

1. Open the workflow and click on the HubSpot connector step
2. In the **Authentication** tab of the properties panel, you will see the currently selected authentication
3. Click the **X button** next to the authentication to deselect it
4. The connector step will no longer use that authentication

![Authentication tab showing the X button to remove the selected authentication from the step](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-remove-auth-from-step.png)

#### Option 2: Delete Authentication Entirely

To delete an authentication from your Tray account:

1. Navigate to the **Authentications** tab in the top navigation
2. Find the **HubSpot authentication** you want to delete in the list
3. Click the **context menu** on the right side of the authentication row
4. Select **Delete**

![Authentications page showing the context menu with the Delete option](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-delete-auth-menu.png)

**If the authentication is not used by any workflow**, a confirmation modal will appear. Click **Delete** to confirm.

![Delete authentication confirmation modal](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-delete-auth-confirm.png)

**If the authentication is still used by one or more workflows**, deletion will be blocked. A **Dependent workflows** modal will appear listing each affected workflow, with an **open** link to navigate directly to it. You must remove the authentication from those workflows before you can delete it.

![Dependent workflows modal showing the authentication cannot be deleted while still in use](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-delete-auth-dependent-wfs.png)

### Revoking Access in HubSpot (Complete Disconnection)

To completely revoke Tray.io's access to your HubSpot account, navigate to the **Connected Apps** page in HubSpot:

1. Log in to your **HubSpot account**
2. Click the **settings icon** (gear icon) in the top navigation bar
3. Navigate to **Integrations → Connected Apps** in the left sidebar

![HubSpot Settings showing Connected Apps in the Integrations menu](https://tray.ai/documentation/images/connectors/service/hubspot/auth-verify-connected-apps.png)

You can use this page to verify that Tray.io is connected and view connection details such as when the connection was authorized, which scopes are granted, and the last activity timestamp.

To uninstall:

4. Find **"Tray.io"** in the list of connected apps
5. Click **Actions** next to Tray.io
6. Select **Uninstall** from the dropdown menu
7. A confirmation modal will appear
8. Type **"uninstall"** to confirm (as required by HubSpot)
9. Click **Uninstall** to revoke access

![HubSpot Connected Apps list showing the Actions menu with the Uninstall option for Tray.io](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-hubspot-actions.png)

![Uninstall Tray.io confirmation modal requiring you to type "uninstall"](https://tray.ai/documentation/images/connectors/service/hubspot/auth-uninstall-hubspot-confirm.png)

> **Info:** After revoking access in HubSpot, all Tray workflows using HubSpot authentications will immediately fail with authorization errors.

#### Step 2: Clean Up Tray Authentications

After revoking in HubSpot, remove the now-invalid authentications from Tray:

1. Go to **Settings → Authentications** in Tray.io
2. Find all **HubSpot authentications** that were connected to the revoked account
3. **Delete each authentication** following the steps in "Delete Authentication Entirely" above
4. Update any workflows that were using these authentications

> **Check:** **Complete Disconnection Achieved!** Tray.io no longer has any access to your HubSpot account.

### What Happens to Workflows After Disconnection?

When you disconnect or revoke HubSpot access:

| Action                               | Impact on Workflows                                | Impact on Authentications                              |
| ------------------------------------ | -------------------------------------------------- | ------------------------------------------------------ |
| **Remove connector from workflow**   | That specific workflow no longer uses HubSpot      | Authentication remains active for other workflows      |
| **Change authentication on step**    | Step stops using old auth, continues with new auth | Old authentication remains active                      |
| **Delete authentication in Tray**    | All workflows using it will fail                   | Authentication permanently deleted                     |
| **Revoke in HubSpot Connected Apps** | All workflows immediately fail with auth errors    | Authentications become invalid but still exist in Tray |

> **Warning:** **Best Practice for Complete Disconnection:**1) First, disable or update all workflows using the HubSpot authentication
> 2) Then, delete the authentication from Tray
> 3) Finally, revoke access in HubSpot Connected AppsThis order prevents workflows from failing unexpectedly in production.

### Re-connecting After Disconnection

If you need to reconnect HubSpot after disconnecting:

1. Follow the **Setup Guide** above to create a new authentication
2. Update all affected workflows to use the new authentication
3. Test each workflow to ensure proper connectivity

> **Info:** You cannot "restore" a revoked authentication - you must create a completely new authentication and re-authorize with HubSpot.

***

## Troubleshooting Authentication Issues

### "Permission Denied" or "Insufficient Permissions" Error

**Problem**: You don't have the required HubSpot permissions to authorize the app.

**Solution**:

* You need **Super Admin** or **App Marketplace access** permissions in HubSpot
* Contact your HubSpot administrator to grant you these permissions
* Alternatively, ask an administrator to create the authentication for your organization

### Authentication Fails During OAuth Flow

**Problem**: OAuth authorization fails or redirects to an error page.

**Solution**:

* Clear your browser cache and cookies
* Try using an incognito/private browsing window
* Ensure you're logging in to the correct HubSpot account
* Check that pop-ups are not blocked by your browser

### "Scope Not Available" Error When Using Operations

**Problem**: An operation fails with a scope-related error.

**Solution**:

* Edit your authentication to add the required scope
* Navigate to **Settings → Authentications**, find your HubSpot auth, and click **Edit**
* Select the additional scopes needed for your operations
* Re-authorize with HubSpot to apply the new scopes

### Authentication Works But No Data Returns

**Problem**: Connection succeeds but operations return empty results.

**Solution**:

* Verify your HubSpot account actually has data (contacts, companies, deals, etc.)
* Check that your scopes include **read** permissions for the objects you're trying to access
* Ensure you're using the correct HubSpot account (if you have multiple)

### "Token Expired" or "Invalid Token" Errors

**Problem**: Authentication worked before but now fails with token errors.

**Solution**:

* HubSpot access tokens can expire or be revoked
* Delete the old authentication and create a new one following the Setup Guide above
* Check HubSpot Connected Apps to ensure Tray.io is still listed and authorized

***

## Additional Resources

* [HubSpot Trigger Documentation](https://tray.ai/documentation/connectors/service/hubspot/hubspot-trigger) - Setting up webhooks and event subscriptions
* [Notes on Using HubSpot](https://tray.ai/documentation/connectors/service/hubspot/notes-on-using-hubspot) - Important implementation notes and scope details
* [Custom OAuth Apps for Embedded Customers](https://tray.ai/documentation/connectors/service/hubspot/notes-for-custom-service-environment) - White-labeling and custom OAuth configuration
* [HubSpot Examples](https://tray.ai/documentation/connectors/service/hubspot/hubspot-examples) - Workflow examples and use cases
* [HubSpot API Documentation](https://developers.hubspot.com/docs/api/overview) - Official HubSpot API reference

> **Info:** For additional support with HubSpot authentication, contact Tray.io support or consult the [HubSpot Developer Community](https://community.hubspot.com/t5/APIs-Integrations/ct-p/apis).