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

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

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

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

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

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.

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

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

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

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

---

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

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

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

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

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.

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

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

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

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

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

---

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 - Setting up webhooks and event subscriptions
• Notes on Using HubSpot - Important implementation notes and scope details
• Custom OAuth Apps for Embedded Customers - White-labeling and custom OAuth configuration
• HubSpot Examples - Workflow examples and use cases
• HubSpot API Documentation - Official HubSpot API reference