How to connect HubSpot

Connecting HubSpot is a single action: click Authorize and sign in with your HubSpot login. There are no credentials to create, copy, or paste — no client ID, no client secret, no API key. Apideck runs the OAuth flow for you and keeps the short-lived access token refreshed afterwards, so the connection keeps working without you re-entering anything.

One HubSpot app and one set of scopes cover both the CRM and the Lead API — leads read and write through HubSpot contacts, and opportunities through HubSpot deals — so there is no second HubSpot connector to set up and no second set of credentials. Each unified API you use does get its own connection in Vault, so if you use both the CRM and the Lead API, authorize both. The second one is quick: the app is already installed in your HubSpot account and no new scopes are requested, so you sign in with the same HubSpot login and confirm.

The one thing worth checking before you click Authorize is whether your HubSpot user is allowed to install apps — that is the single most common reason an otherwise trivial connection fails. The next section covers it.

Prerequisites

A HubSpot account. Any edition works, including the free CRM.
A HubSpot user with the App Marketplace Access permission. HubSpot requires this permission whenever an install asks for scopes the account has not approved yet, which is exactly what a first-time connection does. Super admins have it automatically, so if you are a super admin there is nothing to do here. Otherwise, ask an account admin to grant it — see New permission requirements for installing public apps. Once the app is installed, later re-authorizations by you or a colleague do not need this permission, as long as the scopes have not changed. One exception matters: if the app is uninstalled from your HubSpot account, HubSpot treats the next install as a brand-new app with no granted permissions, so App Marketplace Access is needed again for that install.
The permissions the requested scopes imply. The app's requirements are listed on its App Marketplace listing page under Requirements → HubSpot Account permissions. In practice the one most often missing is Edit property settings, which a user needs if the integration creates or updates HubSpot properties (custom fields).
The right HubSpot account in mind. A connection is anchored to the single HubSpot account you install into. If your login has access to more than one, make sure you install into the one this connection is for.

1. Authorize with HubSpot

Open the HubSpot connection in Apideck Vault and click Authorize. Vault redirects you to HubSpot.
Sign in with the HubSpot account this connection should use. If HubSpot asks which account to install the app into, choose the one this connection is for.
Review the access HubSpot lists on the install screen and confirm it.
HubSpot returns you to Vault and the connection is authorized.

You are never asked for a redirect URL, a client ID, or a client secret. Those belong to the HubSpot app held by the provider of the integration — see the HubSpot OAuth credentials guide if you are the one who set that app up.

2. Set the defaults for new records

HubSpot has a few settings in Vault that decide what happens to records the integration creates without specifying every field. Set them after authorizing: the dropdowns are populated live from your own HubSpot account, so they need the connection to be in place first.

Resource	Setting	Required	What it does
Opportunities	Pipeline	Yes	The pipeline an opportunity is created in when the request does not name one. Lists the pipelines in your HubSpot account.
Opportunities	Stage	Yes	The stage within that pipeline. The list is filtered to the pipeline you picked above, so choose the pipeline first.
Contacts	Lifecycle stage	No	The lifecycle stage applied to every contact the integration creates while this setting has a value. Leave it empty to let HubSpot's own default apply.
Leads	Lifecycle stage	No	The same, for newly created leads. It is a separate setting from the contacts one even though the label is identical — set both if you create both.

Pipeline and Stage are the two required ones, and they are worth a deliberate choice rather than the first entry in the list: every opportunity the integration creates without an explicit pipeline and stage lands where you point them here. An integration can still name a different pipeline and stage on an individual request, so an opportunity that appears somewhere other than these defaults is expected behaviour rather than a broken setting. The Lifecycle stage settings work differently: a request cannot override them, so they are the only place that value comes from.

You may also see a free-text Portal id field. It belongs to HubSpot's tracking-script surface, not to the CRM or Lead APIs — no CRM or Lead operation in this connector reads it. Leave it blank unless the provider of the integration asks you to fill it in.

Notes

Token refresh is automatic. HubSpot access tokens are short-lived (30 minutes) and Apideck refreshes them for you. There is nothing to rotate, re-enter, or monitor, and HubSpot documents no scheduled expiry for the underlying authorization.
Uninstalling the app in HubSpot ends the connection. This is the one action that reliably breaks it. If the app is uninstalled from Integrations → Connected Apps in your HubSpot settings (Actions → Uninstall), the connection stops working until someone authorizes it again in Vault — and because HubSpot treats that re-install as a brand-new app with no granted permissions, whoever does it needs the App Marketplace Access permission again. See Connect apps to HubSpot.
A connected app is not left without an owner when someone leaves. If the HubSpot user who owns the app is deactivated, HubSpot prompts for ownership to be reassigned before completing the deactivation. See Manage your connected apps.
Re-authorizing is safe and is the standard repair. Opening the connection in Vault and clicking Authorize again is the fix for most problems below; it does not require you to gather anything first. The one thing to line up first is the permission above, if the app was uninstalled in the meantime.

Troubleshooting

"Couldn't complete the connection. You don't have permission to connect this integration." Your HubSpot user is missing the App Marketplace Access permission, or one of the permissions the app's scopes require. Ask a HubSpot account admin to grant App Marketplace Access, then check the app listing's Requirements → HubSpot Account permissions for anything else you are missing — Edit property settings is the usual one. HubSpot's Resolve a 'Request for Integration Permissions' error walks an admin through it. Then click Authorize again.

Authorization fails with an "insufficient scopes" error. The scopes configured on the HubSpot app do not match the scopes Apideck requests, so HubSpot refuses the install. Nothing on your side can change this and re-trying will not clear it — report it to the provider of the integration. They own the HubSpot app and can correct its scopes, after which your Authorize click will go through.

The wrong HubSpot account got connected. The connection is anchored to the account the app was installed into. Sign in to HubSpot as the account you actually want (or switch accounts there), then run Authorize again on the connection.

New opportunities show up in an unexpected pipeline or stage. Check the Pipeline and Stage settings on the connection (step 2) — those are the defaults used whenever a request does not name its own. If the integration sets them per request, the setting is not what decides it; raise it with the provider of the integration.

New contacts or leads have an unexpected lifecycle stage. Only two things can produce it: the Lifecycle stage setting for that resource, and — when that setting is empty — HubSpot's own default. A request cannot override the setting, so start there: clear it to fall back to HubSpot's default, or set it to the stage you want.

Requests start failing with 429. That is HubSpot's rate-limit answer, not a broken connection — nothing needs re-authorizing and it recovers on its own once the window resets. The budget is shared by every connection using the same HubSpot app for your account, so it can be tripped by activity that is not yours. If it keeps happening, report it to the provider of the integration: pacing the calls is theirs to manage, and the current limits are listed in this connector's overview.

The connection worked and later stopped. The usual causes, in order:

The app was uninstalled in HubSpot — authorize again in Vault, using a HubSpot user that has App Marketplace Access, since HubSpot treats the re-install as a brand-new app with no granted permissions.
The HubSpot app credentials behind the integration changed. That sits with the provider of the integration and affects every connection using them, so report it to them rather than re-authorizing repeatedly.

Still stuck? Contact Apideck Support.