{"slug":"hubspot","name":"HubSpot","domain":"hubspot.com","category":"CRM","summary":"You can create a HubSpot OAuth app and connect real customer accounts on the same day, but a marketplace-distribution app is capped at 25 installs until it is listed on the HubSpot Marketplace. Listing needs at least 3 active installs from production accounts not affiliated with you, live public URLs, and a review by HubSpot's Ecosystem Quality team. The first review takes up to 10 business days, and the full feedback process can run up to 60 days.","tier":"capped","tierReason":"Real customers can install an unlisted marketplace OAuth app today, after you sign the Acceptable Use Policy (AUP), but only up to 25 accounts until HubSpot approves a Marketplace listing.","quality":"researched","updatedAt":"2026-10-27","composio":{"status":"managed","note":"Composio has a managed HubSpot OAuth app, so you can prototype before you register your own. Register your own app before launch so your app's name is on the install screen and the 25-install cap and Marketplace listing are under your control.","toolkit":"HUBSPOT"},"totals":{"effort":{"min":1,"max":3,"unit":"days"},"wait":{"min":2,"max":12,"unit":"weeks"},"firstConnection":"Today, in about 1 hour (in a developer test account or your own HubSpot account)"},"stages":[{"id":"build","name":"Developer and test accounts","whoCanConnect":"Your developer test accounts, which don't count toward install limits, and your own standard HubSpot account","userSees":"An unverified-app warning on the install screen, with a checkbox to confirm before clicking Connect app","effort":{"min":30,"max":90,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Sign the Acceptable Use Policy for your marketplace-distribution app so accounts that aren't test accounts can install it","evidence":{"kind":"docs","sources":["s3","s4"],"confidence":"high"}},{"id":"beta","name":"Unlisted, up to 25 installs","whoCanConnect":"Any HubSpot account, up to 25 installs (developer test accounts don't count). A super admin, or a user with the Marketplace access permission, does the install.","userSees":"An unverified-app warning until HubSpot's Ecosystem Quality team verifies the app","effort":{"min":1,"max":4,"unit":"hours"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Get 3 active installs from unaffiliated production accounts, then have HubSpot approve your Marketplace listing","evidence":{"kind":"docs","sources":["s2","s3"],"confidence":"high"}},{"id":"launch","name":"Listed on the Marketplace","whoCanConnect":"Any HubSpot account, with no install cap","userSees":"A normal install screen for a listed app","effort":{"min":4,"max":16,"unit":"hours"},"wait":{"min":2,"max":12,"unit":"weeks"},"unlock":null,"evidence":{"kind":"docs","sources":["s2","s5"],"confidence":"medium"}}],"requirements":[{"id":"hubspot-developer-account","label":"HubSpot developer account","detail":"You need a HubSpot account that can create developer platform projects and developer test accounts.","stage":"build","actor":"you","evidence":{"kind":"docs","sources":["s4"],"confidence":"medium"}},{"id":"hubspot-cli","label":"HubSpot CLI v7.6.0 or later","detail":"New apps on developer platform 2025.2 are created as projects with the CLI (`hs project create`, `hs project upload`).","stage":"build","actor":"agent","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"https-redirect-uri","label":"Redirect URI for your OAuth client","detail":"The callback URL your OAuth client uses. You list it in `config.auth.redirectUrls`.","stage":"build","actor":"agent","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"acceptable-use-policy","label":"Signed Acceptable Use Policy","detail":"Marketplace OAuth apps must sign the AUP before they can be installed in accounts that aren't developer test accounts.","stage":"beta","actor":"you","evidence":{"kind":"docs","sources":["s3"],"confidence":"high"}},{"id":"three-active-installs","label":"3 active installs from unaffiliated customers","detail":"You need at least 3 unique HubSpot production accounts, not affiliated with you, with successful app activity in the past 30 days.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}},{"id":"public-legal-support-urls","label":"Live terms, privacy policy, support and pricing pages","detail":"Your terms of service, privacy policy and support URLs must be live and public, and listed pricing must match your website. HubSpot checks the links with a crawler.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}},{"id":"tech-partner-agreement","label":"Technology Partner Program Agreement","detail":"Listing requires agreeing to HubSpot's Technology Partner Program Agreement.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}}],"steps":[{"id":"install-cli","title":"Install and authenticate the HubSpot CLI","actor":"you","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"Install the CLI (v7.6.0 or later) and run `hs account auth` to link it to your HubSpot account. Signing in and creating the personal access key needs a person.","actions":["npm install -g @hubspot/cli@latest","hs account auth","Optional: create a configurable developer test account"],"agentNote":"An agent can run the install command once you've done the browser sign-in for `hs account auth`.","gotcha":"Older CLI versions don't create apps on platform 2025.2.","link":{"label":"Create an app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},"evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"create-project","title":"Create an app project with OAuth auth","actor":"agent","stage":"build","time":{"min":10,"max":20,"unit":"minutes"},"detail":"Run `hs project create` and pick App. Choose Marketplace distribution and OAuth authentication, then give the app a unique `uid` in `app-hsmeta.json`.","actions":["hs project create → base contents: App","Distribution: Marketplace","Auth: OAuth","Set a unique uid in app-hsmeta.json"],"agentNote":"An agent can do all of this.","gotcha":"If you choose private (allowlist) distribution, you're capped at 10 accounts (100 for Solutions Partners), and the app can't be listed until you switch it to marketplace distribution. Changing a uid after upload creates a new component.","link":{"label":"Create an app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},"evidence":{"kind":"docs","sources":["s4","s2"],"confidence":"high"}},{"id":"configure-auth","title":"Set redirect URLs and scopes","actor":"agent","stage":"build","time":{"min":10,"max":20,"unit":"minutes"},"detail":"In `app-hsmeta.json`, set `config.auth.type` to `oauth`, add your redirect URI to `redirectUrls`, and list `requiredScopes`, `optionalScopes` and `conditionallyRequiredScopes`. Also fill in name, description, support and permittedUrls.","actions":["config.auth.redirectUrls: [your redirect URI]","config.auth.requiredScopes: e.g. crm.objects.contacts.read, crm.objects.contacts.write","Put non-essential scopes in optionalScopes"],"agentNote":"An agent can edit the file. Ask the developer which scopes the integration needs.","gotcha":"The redirect URI must match your OAuth client exactly, including http vs https. Every required scope must be available in the installing account, or the install fails, so put non-essential scopes in optionalScopes.","link":{"label":"Create an app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app"},"evidence":{"kind":"docs","sources":["s4","s6"],"confidence":"high"}},{"id":"upload-project","title":"Upload the project to HubSpot","actor":"agent","stage":"build","time":{"min":2,"max":10,"unit":"minutes"},"detail":"Run `hs project upload` to build and deploy the app. Run it again after any scope or redirect change.","actions":["hs project upload"],"agentNote":"An agent can run this.","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"copy-credentials","title":"Copy the client ID and secret","actor":"you","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"Run `hs project open`, click the app under Project Components and open the Auth tab. Copy the client ID and client secret into your OAuth client's configuration.","actions":["hs project open","Project Components → your app → Auth tab","Copy Client ID and Client secret into your OAuth client"],"agentNote":"An agent can open the page and copy the client ID. A person must handle the client secret.","image":{"url":"https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/app-authentication-details-no-app-id.png","alt":"Client credentials section on the app's Auth tab, showing Client ID and Client secret","source":"s4"},"evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"test-install","title":"Install the app in a test account","actor":"agent","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"Under Development → Test accounts, create a test account. Then on your app's Distribution tab, click Add test install(s), then Install, tick the unverified-app checkbox and click Connect app. You can also install in your own standard account with Install now.","actions":["Development → Test accounts → create","Projects → your project → app UID → Distribution → Add test install(s) → Install","Confirm the unverified-app checkbox → Connect app"],"agentNote":"An agent can click through this once you're signed in and test the token exchange in your OAuth client.","image":{"url":"https://www.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer/install-new-app-in-test-account.png","alt":"Distribution tab showing where to add a test install","source":"s4"},"evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"sign-aup","title":"Sign the Acceptable Use Policy","actor":"you","stage":"beta","time":{"min":5,"max":15,"unit":"minutes"},"detail":"On the app's Distribution tab, sign the AUP so standard HubSpot accounts can install the app through its install URL without an allowlist. After that, up to 25 accounts can install it.","actions":["Distribution tab → sign Acceptable Use Policy","Share the sample install URL with customers"],"agentNote":"Hand back to the developer to accept the policy.","gotcha":"Users still see an unverified-app warning, and install 26 fails until the app is listed.","link":{"label":"Manage apps in HubSpot","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot"},"evidence":{"kind":"docs","sources":["s3"],"confidence":"high"}},{"id":"get-active-installs","title":"Get 3 active installs from real customers","actor":"you","stage":"beta","time":{"min":1,"max":4,"unit":"hours"},"detail":"Onboard at least 3 production HubSpot accounts that aren't affiliated with you, and make sure each has successful app activity in the last 30 days.","gotcha":"Your own accounts and developer test accounts don't count.","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}},{"id":"submit-listing","title":"Submit your Marketplace listing","actor":"you","stage":"launch","time":{"min":4,"max":12,"unit":"hours"},"detail":"Create the listing with a description, pricing that matches your site, support contact, and live terms, privacy and support URLs. Agree to the Technology Partner Program Agreement, then submit.","actions":["Allowlist the HubSpot Crawler user agent on your site","Check that every listing URL is live and public","Agree to the Technology Partner Program Agreement","Submit for review"],"agentNote":"An agent can draft listing copy and check that the links work. A person must accept the agreement and submit.","gotcha":"Broken or crawler-blocked links are a common reason listings get sent back. Only one app can be in review at a time. Others you submit meanwhile are rejected automatically.","link":{"label":"Listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements"},"evidence":{"kind":"docs","sources":["s5","s7"],"confidence":"high"}},{"id":"listing-review","title":"Wait for Ecosystem Quality review","actor":"provider","stage":"launch","time":{"min":2,"max":12,"unit":"weeks"},"detail":"The initial review takes up to 10 business days. Rounds of feedback can stretch the full process to about 60 days after feedback is shared. Approval removes the 25-install cap automatically.","gotcha":"A listing can go back to draft without an email. Ask HubSpot support or the Ecosystem Quality team for the reason.","evidence":{"kind":"docs","sources":["s5","s7"],"confidence":"medium"}}],"scopes":{"intro":"Most CRM scopes (for example crm.objects.contacts.read/write) are self-serve: you declare them in app-hsmeta.json. Sensitive-data scopes need HubSpot's approval for public apps.","tiers":[{"scope":"crm.objects.contacts.read / crm.objects.contacts.write and other standard CRM scopes","grants":"Read and write standard CRM records","level":"basic","consequence":"Nothing beyond the 25-install cap and Marketplace listing"},{"scope":"crm.objects.contacts.sensitive.read (and other *.sensitive.* / highly sensitive scopes)","grants":"Read and write values of Sensitive Data properties","level":"restricted","consequence":"Public apps must request access from the Ecosystem Quality team, which allowlists the scope for testing and runs compliance checks before publishing. Existing users must reauthorize. Installing accounts need Enterprise."}]},"blockers":[{"symptom":"Installs fail after the 25th account","cause":"Marketplace-distribution apps on developer platform 2025.2 are capped at 25 installs until they are listed. HubSpot has enforced this since September 22, 2025.","fix":"Get your Marketplace listing approved. HubSpot makes no exceptions, and the cap lifts automatically on approval. Migrated legacy apps already above 25 should file a support request.","evidence":{"kind":"docs","sources":["s2","s7"],"confidence":"high"}},{"symptom":"Customers can't install the app outside test accounts","cause":"The Acceptable Use Policy hasn't been signed, or the app uses private distribution and the account isn't on the allowlist.","fix":"Sign the AUP on the Distribution tab, or add the account to the allowlist for private apps.","evidence":{"kind":"docs","sources":["s3"],"confidence":"high"}},{"symptom":"Listing review can't start: not enough installs","cause":"Listing needs 3 active installs from unaffiliated production accounts.","fix":"Use the 25-install allowance to onboard early customers first, then submit.","evidence":{"kind":"docs","sources":["s5"],"confidence":"high"}},{"symptom":"Listing sent back to draft","cause":"Often broken or unreachable links, or the HubSpot crawler is blocked.","fix":"Fix the URLs, allowlist the HubSpot Crawler, and ask Ecosystem Quality for the exact reason.","evidence":{"kind":"community","sources":["s7"],"confidence":"medium"}}],"unknowns":[{"question":"Can you still create new legacy public apps (outside projects) that avoid the 25-install cap?","why":"The docs found focus on platform 2025.2 and only say that migrated apps get the cap.","resolve":"Check the Apps section of your developer account, or ask HubSpot developer support."},{"question":"How long do reviews take in practice, beyond the documented 10 business days for the first review and 60 days for the full process?","why":"No dated community reports of real turnaround times were found, and one community thread couldn't be fetched.","resolve":"Search the HubSpot Developer Community for recent listing threads, or ask your HubSpot partner contact."},{"question":"Does the cap count installs per portal or per user?","why":"Docs say 'accounts'. One third-party blog says per portal but admits this isn't confirmed.","resolve":"Ask HubSpot developer support."}],"handoff":{"agentCan":["Run hs project create / upload / open after the CLI is authenticated","Edit app-hsmeta.json with your redirect URI and scopes","Create developer test accounts and run test installs","Copy the client ID into your OAuth client and test the connection","Draft Marketplace listing copy and check that the links work"],"youMust":["Sign in and authenticate the CLI","Handle the client secret","Sign the Acceptable Use Policy","Recruit 3 unaffiliated active customers","Agree to the Technology Partner Program Agreement and submit the listing","Request sensitive-data scopes from Ecosystem Quality if you need them"]},"sources":[{"id":"s1","title":"Composio managed auth toolkits","url":"https://docs.composio.dev/toolkits/managed-auth.md","publisher":"Composio docs","kind":"composio","checkedAt":"2026-10-27"},{"id":"s2","title":"New marketplace distribution app install limits","url":"https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits","publisher":"HubSpot developer changelog","kind":"official","checkedAt":"2026-10-27"},{"id":"s3","title":"Manage apps in HubSpot","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot","publisher":"HubSpot developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s4","title":"Create an app","url":"https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app","publisher":"HubSpot developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s5","title":"App Marketplace listing requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements","publisher":"HubSpot developer docs","kind":"official","checkedAt":"2026-10-27"},{"id":"s6","title":"Access and manage sensitive data","url":"https://developers.hubspot.com/docs/api/sensitive-data","publisher":"HubSpot developer docs","kind":"search","checkedAt":null},{"id":"s7","title":"App installs limit","url":"https://community.hubspot.com/t/app-installs-limit/152805","publisher":"HubSpot Community","kind":"search","checkedAt":"2026-10-27"},{"id":"s8","title":"Certification requirements","url":"https://developers.hubspot.com/docs/apps/developer-platform/list-apps/apply-for-certification/certification-requirements","publisher":"HubSpot developer docs","kind":"search","checkedAt":null}],"feedback":{}}