OAuth app readiness guide · CRM

Getting your HubSpot app ready for real users

Checked against official docsChecked 2026-10-27hubspot.com

Verdict. A HubSpot OAuth app works the same day, then stops at 25 customer installs until your Marketplace listing is approved. New apps are built as projects with HubSpot's CLI, not just in a web form.

At a glance

The answer in one screen

Ease of creation

Moderate

CLI project setup on the developer platform (2025.2+). Not tested by us.

Ease of approval

Capped until review

25 installs before Marketplace approval.

Your hands-on time

2 to 4 hours

Developer account, CLI project, config file, upload.

Waiting on the provider

Not published

Marketplace review timeline not stated on pages we read.

Do you need your own app yet?

Check Composio first.

Composio publishes a HubSpot custom-app guide; managed availability not confirmed.

Watch out: decisions you can't undo

The 25-install cap applies to new and migrated apps. Do not migrate a busy legacy app without a listing plan.
Required vs optional scopes shape installs. Put anything your agent can live without into optional scopes.

Agent an agent can do it You needs you Waiting on the provider

Prerequisites

What to have ready

To create and connect

HubSpot developer account
HubSpot CLI installed
Redirect URL

For approval (can take days)

Signed Acceptable Use Policy (Distribution tab, "Begin publishing")
Marketplace listing content

App types

Which one is right for an agent product?

Static token (private)

Single account auth.

Who can install: 1 standard account + 10 developer test accounts
Review: None
Use it for: Internal scripts

Private OAuth

distribution: private.

Who can install: Up to 10 allowlisted accounts
Review: None
Use it for: Pilots with named customers

Recommended for agents

Marketplace OAuth

distribution: marketplace.

Who can install: 25 accounts before listing; unlimited after
Review: Marketplace listing review
Use it for: Agent products with customers

Conflicting limit for private OAuthThe Manage apps page says 10 allowlisted accounts. The changelog says 10 for app partners and 100 for Solution Partners.

Creation steps

Who does what, and how long it takes

YouCreate a developer account
15 min
Apps live in projects on the developer platform.
AgentScaffold the project with the CLI
45 min
Set auth to OAuth, distribution to marketplace, redirectUrls and scopes in app-hsmeta.json.
YouBegin publishing and sign the AUP
10 min
Until signed, installs only work in developer test accounts.
AgentCopy credentials into Composio
5 min
Development, Projects, your app, Auth tab.
WaitingMarketplace listing review
Unknown
Needed beyond 25 installs.

Scopes

What each permission costs you

Scopes are set in app-hsmeta.json as required or optional and uploaded with hs project upload.

Agent use case	Scopes	What it costs you
Read contacts	`crm.objects.contacts.read`	Standard
Write contacts	`crm.objects.contacts.write`	Standard
Deals and companies	`crm.objects.deals.readcrm.objects.companies.read`	Standard

Minimal set: "CRM lookup" agentcrm.objects.contacts.readcrm.objects.companies.read

Mark write scopes optional.

Changing scopes later

Edit app-hsmeta.json and run hs project upload.
Existing installs must reauthorize for new required scopes (not verified).

Approval and distribution

Review, cost and renewal

When you need it: To go beyond 25 installs. Cost: Not stated on pages we read. Renewal: Not stated.

Listing review

Not published

Check current listing requirements before planning dates.

What you submit

Listing content
Install and usage requirements per HubSpot's listing rules

Common rejection reasons

Not documented on pages we read

Before approval: what works and what's capped

Build and test

Developer test accounts.

Limit: Must sign the AUP to install elsewhere.

First customers

Marketplace-distribution app, unlisted.

Limit: 25 installs, excluding developer test accounts.

Scale

Approved listing.

Limit: Unlimited installs.

Data use and compliance

Rules that shape agent design

Acceptable Use Policy must be signed before installing outside test accounts.

Common blockers

Symptom, cause, fix

Symptom	Cause	Fix
Install fails after 25 customers	Marketplace install cap	Get the listing approved
Can only install in test accounts	AUP not signed	Distribution tab, Begin publishing

Sources

Where every claim comes from

Claim	Source
25-install cap before listing	Official docs
Review duration	Not verified

All sources

HubSpot changelog: install limits developers.hubspot.com
HubSpot: Manage apps developers.hubspot.com