# HubSpot (developer platform apps with OAuth): OAuth app setup guide

> Curated guide, updated 2026-10-30. Source: https://oauthseus.vercel.app/guides/hubspot

**Difficulty:** moderate. An afternoon to a working OAuth app for up to 25 customers; then 3 active installs plus roughly 2-10 weeks of Marketplace review to remove the cap _[documented s3,s4]_

New HubSpot OAuth apps are now built only as CLI-driven 'projects' on the developer platform (2025.2 / 2026.03 / 2026.09). The old 'Create app' UI flow for legacy public apps was switched off in May/June 2026. A marketplace-distributed OAuth app works for real customers in an afternoon with no review, but it is capped at 25 installs until HubSpot lists it on the Marketplace. Listing needs 3 active installs and a manual review: initial response within 10 business days, and up to 60 days of back-and-forth after feedback. If your product is an AI connector, the listing rules require user-level access (platform 2026.09) or HubSpot's MCP server, and you have to decide that when you create the app.

**Your work:** 3–8 hours. **Waiting on provider:** 2–10 weeks (review depends on path).

Nothing is reviewed for developer test accounts, private distribution (up to 10 allowlisted accounts) or an unlisted marketplace-distribution app (up to 25 installs; you only sign the Acceptable Use Policy in the Distribution tab). Going past 25 installs requires a HubSpot Marketplace listing, which the HubSpot Ecosystem Quality team reviews manually. HubSpot says the initial review happens within 10 business days and the whole feedback process should take no more than 60 days from when feedback is shared. Before you can submit, you need 3 active installs: production accounts unaffiliated with you, each with successful API activity in the past 30 days. Certification is a separate, optional review. It is only open after 6 months listed and 60 active installs, and HubSpot publishes no turnaround time for it.

## Launch paths

| Path | Difficulty | Your work | Provider wait |
|---|---|---|---|
| Single account only: service key or static-auth app (not OAuth) | easy | 10–30 min | None |
| Privately distributed OAuth app (allowlisted accounts) | easy | 2–5 hours | None |
| Marketplace-distribution OAuth app, unlisted (default for agent builders) | moderate | 3–8 hours | None |
| Listed on the HubSpot Marketplace (unlimited installs) | moderate | 1–3 days | 2–10 weeks |
| Certified Marketplace app | hard | 2–5 days | None |

## Do these first

1. Decide now whether you will list as an AI connector. If yes, start on platform 2026.09 with isUserLevel: true, because this cannot be changed later
2. Create a developer account and a developer test account, then install the CLI and run `hs account auth`
3. Run `hs project create` (App, marketplace distribution, oauth) and set redirectUrls plus minimal requiredScopes
4. Run `hs project upload`, copy the client ID and secret from the Auth tab, and wire the OAuth callback using the date-based token endpoint
5. Sign the AUP via 'Begin publishing', verify your domain, and onboard 3 real customers so you can submit a listing before you near the 25-install cap

## What you're registering

**App (project component) in a HubSpot developer project, built with the HubSpot CLI and configured in app-hsmeta.json.** You create one app in your developer account; it is a component inside a 'project' that you upload with `hs project upload`. Configuration such as the name, distribution (marketplace or private), auth type (oauth or static), redirectUrls and scopes lives in `src/app/app-hsmeta.json` in your repo, not in UI forms. To change redirect URLs or scopes, edit the file and re-upload. Each end user's connection is an install of your app into one HubSpot account (portal). Installs are account-level by default. With `isUserLevel: true` (platform 2026.09), each user installs separately and the app acts with that user's permissions. The UI only shows credentials, distribution, test installs and listings. Legacy public apps (pre-Projects, created in the old 'Apps > Create app' UI) can no longer be created. They go unsupported, with enforcement in September 2027.

This is the authorization-code flow. The authorize URL is https://app.hubspot.com/oauth/authorize with client_id, redirect_uri, scope (space-separated required scopes), optional_scope and state. Exchange the code at the date-based token endpoint (docs show POST https://api.hubspot.com/oauth/2026-09/token; the May 2026 changelog lists /oauth/2026-03/token). The legacy /oauth/v1/token still works but is being deprecated, and new listings must use the v3 endpoints. Access tokens expire after 1800 seconds (30 minutes), so refresh proactively with grant_type=refresh_token. The response's hub_id identifies the connected portal, so store tokens keyed by hub_id (and by user for user-level apps). Optional scopes can be dropped at install, so read the granted scopes from the token response or introspection. Changing required scopes means existing installs must re-authorize. Rotating the client secret (Auth tab > Rotate) invalidates the old secret immediately.

## What you'll need

- **HubSpot developer account (free) + HubSpot CLI**: Sign up for an app developer account, install Node.js and `npm install -g @hubspot/cli@latest`, then run `hs account auth`, which uses a personal access key from Development > Keys. The docs require CLI v7.6.0 or later for 2025.2/2026.03 apps and v8.15.0 for 2026.09 user-level apps. _[documented s1,s12]_
- **HTTPS redirect URL on a domain**: At least one entry in auth.redirectUrls. It must be HTTPS, except that http://localhost is allowed for testing. IP addresses are not supported, so http://127.0.0.1 will fail; use localhost. _[documented s2,s10]_
- **At least one required scope**: requiredScopes must contain at least one scope, at minimum the read scope for the object you touch (e.g. crm.objects.contacts.read). OAuth apps can also declare optionalScopes, which the installer can untick and which are dropped if the account lacks the tool. They can also declare conditionallyRequiredScopes, which become required only when you pass them in the install URL's scope parameter. Static-auth apps can only declare required scopes. _[documented s2]_
- **OAuth backend (token exchange + refresh)**: A server that receives the code at your redirect URL, exchanges it with the client secret, stores refresh tokens per hub_id, and refreshes access tokens every ~30 minutes. HubSpot's oauth-quickstart-nodejs sample works with http://localhost:3000/oauth-callback. _[documented s11]_
- **Signed Acceptable Use Policy**: Marketplace-distribution apps: on the Distribution tab, click 'Begin publishing' and sign the AUP before any non-test account can install. _[documented s3]_
- **Verified domain (recommended)**: Development > Domain > Verify a domain, then add a DNS TXT record. This replaces the scary 'unverified app' install warning with your domain name, though a 'not reviewed by HubSpot' banner remains until listing. Only one verified domain is allowed per developer account. _[documented s3]_
- **3 active, unaffiliated production installs**: These are needed before you can submit a listing. Active means successful OAuth-authenticated API calls, signed webhook requests or extension requests in the past 30 days, from HubSpot production accounts not affiliated with your organization. Test accounts and your own portals do not count. _[documented s4]_
- **Public listing assets**: Live, crawlable URLs for: integration-specific setup documentation, privacy policy, terms of service, a support site and an install button URL. You also need pricing that matches your website and an accurate 'Shared data' table matching your scopes. Allowlist the 'HubSpot Crawler' user agent so URL checks do not fail. _[documented s4]_
- **Technology Partner Program Agreement**: Accept HubSpot's Technology Partner Program Agreement as part of listing. _[documented s4]_
- **User-level access or HubSpot MCP server (AI connectors)**: If your app primarily connects HubSpot to external generative-AI tools, the listing rules say it must require user-level permissions (isUserLevel: true, platformVersion 2026.09) or be built with HubSpot's remote MCP server. This has to be decided before you create the app, because account-level apps cannot be migrated to user-level. _[documented s4,s12]_
- **Supported platform version and OAuth v3 endpoints**: From Nov 2, 2026, new listings must be on developer platform v2025.2 or v2026.03 per the changelog (2026.09 is the newest version). New listings and certifications must use the date-based OAuth v3 token endpoints, not /oauth/v1. _[documented s6]_
- **Certification: 6 months listed, 60 active installs, demo video, security questionnaire, uninstall endpoint**: Submit a YouTube demo video of at least 3 minutes that shows install, setup, use, disconnect and uninstall. Keep an API success rate above 95%, use DELETE /appinstalls/v3/external-install, and complete the token storage security questionnaire. _[documented s14,s6]_

## Steps

### 1. Create a HubSpot developer account and a developer test account (10–20 min, you)

1. Sign up for a free app developer account at developers.hubspot.com (Get started / create a developer account).
2. In the developer account, navigate to Development, then Test accounts, and click 'Create developer test account'. Follow the prompts.
3. Test accounts are where you install and exercise the app without spending one of your 25 (or 10) production installs.

[Create an app (prerequisites and test accounts)](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app) · [Account types](https://developers.hubspot.com/docs/getting-started/account-types) _[documented s1]_

### 2. Install and authenticate the HubSpot CLI (10–20 min, agent prepares, you submit)

1. Run `npm install -g @hubspot/cli@latest` (v7.6.0+ required; v8.15.0+ if you want user-level access on 2026.09).
2. Run `hs account auth`. It opens HubSpot to generate a personal access key (Development > Keys > Personal access key). Copy the key back into the terminal.
3. Confirm with `hs account list`.
   - Install command: `npm install -g @hubspot/cli@latest`
   - Auth command: `hs account auth`

[Install the CLI](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli) · [Manage keys](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) _[documented s3]_

### 3. Decide distribution, auth type and user-level vs account-level BEFORE creating the app (15–45 min, agent prepares, you submit)

1. Distribution: choose 'marketplace' if you want any customer to connect (25-install cap until listed). Choose 'private' for up to 10 allowlisted portals. You can switch private to marketplace later without breaking installs.
2. Auth: choose 'oauth' for multi-account connections. 'static' is for a single account only.
3. If your product is an AI agent or connector that brings HubSpot data into an LLM and you intend to list, plan for user-level access: set platformVersion 2026.09 in hsproject.json and isUserLevel: true in app-hsmeta.json. User-level apps do not support webhooks, app cards, serverless functions or custom workflow actions, and only some APIs work (CRM objects broadly do; bulk associations and some others do not).
4. Existing account-level apps cannot be converted to user-level. You would need a new app (new client ID), and every customer would have to reconnect.
   - hsproject.json platformVersion: `2026.09` (Required for isUserLevel)
   - app-hsmeta.json config.isUserLevel: `true` (Only if you choose user-level access)

[User-level access](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/user-level-apps) · [Listing requirements (AI connectors)](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements) _[documented s12,s4]_

### 4. Scaffold the app with `hs project create` (15–30 min, agent can do)

1. Run `hs project create`. When asked for the base contents, select App.
2. At the prompts choose --distribution (marketplace or private), --auth (oauth), and any --features (Card, App Function, Settings, Webhooks, Custom Workflow Action). Pick none if you only need API access.
3. In src/app/app-hsmeta.json, set a unique `uid` (do not change it after the first upload), the app `name`, `description` and `support` contact details.
   - Command: `hs project create`

[Create a new app using the CLI](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app) · [App configuration reference](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration) _[documented s1]_

### 5. Configure redirect URLs and scopes in app-hsmeta.json (20–60 min, agent can do)

1. Set auth.type to "oauth".
2. Add redirectUrls. Each must be HTTPS except http://localhost, and it must be a domain, not an IP address. Include both your local dev callback and your production callback.
3. Put scopes every customer must grant in requiredScopes (at least one). Put scopes only some customers can grant (e.g. Enterprise-only tools) in optionalScopes. Put scopes you request per install via the install URL's scope parameter in conditionallyRequiredScopes.
4. Request only scopes you actually use. Unused scopes are a listing rejection reason and must also appear in the listing's Shared data table.
   - auth.type: `oauth`
   - auth.redirectUrls: `["http://localhost:3000/oauth-callback", "https://YOUR_DOMAIN/oauth/hubspot/callback"]`
   - auth.requiredScopes: `["crm.objects.contacts.read"]` (Example; add only what your agent uses)
   - auth.optionalScopes: `[]`
   - auth.conditionallyRequiredScopes: `[]`

[App configuration: authentication](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration) · [Scopes reference](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/scopes) _[documented s2]_

### 6. Upload the project and copy the client ID and secret (10–20 min, agent prepares, you submit)

1. Run `hs project upload`. This builds and deploys the project.
2. Run `hs project open` (or go to Development > Projects and click your project name).
3. Under Project Components, click your app's name, then click the Auth tab.
4. Under Client credentials, copy the Client ID and Client secret into your backend's secret store. Redirect URLs are listed at the bottom of this tab.
5. If the secret leaks, click Rotate next to it, then 'Rotate secret'.
   - Commands: `hs project upload && hs project open`

[Locate client credentials](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) _[documented s3]_

### 7. Implement the OAuth flow and token refresh (1–4 hours, agent can do)

1. Build the authorize URL: https://app.hubspot.com/oauth/authorize?client_id=...&redirect_uri=...&scope=<space-separated required scopes>&optional_scope=<optional>&state=<csrf>. The scope parameter must include every required scope, or the authorization page shows an error.
2. On callback, verify state, then POST (form-encoded) code, redirect_uri, client_id, client_secret and grant_type=authorization_code to the date-based token endpoint (docs: https://api.hubspot.com/oauth/2026-09/token). Avoid /oauth/v1/token for anything you plan to list.
3. Store refresh_token keyed by hub_id (and by user for user-level apps). Treat access tokens as valid for expires_in seconds (1800) and refresh with grant_type=refresh_token shortly before expiry.
4. Read the granted scopes from the token response or introspection, because optional scopes may be missing.
5. Implement uninstall using DELETE /appinstalls/v3/external-install. This is required for certification.
   - Authorize URL: `https://app.hubspot.com/oauth/authorize`
   - Token URL: `https://api.hubspot.com/oauth/2026-09/token` (The May 2026 changelog lists /oauth/2026-03/token; use the version your docs page shows)
   - Access token lifetime: `1800 seconds`

[Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) · [Manage OAuth tokens (latest API)](https://developers.hubspot.com/docs/api-reference/latest/authentication/manage-oauth-tokens) · [OAuth quickstart (Node.js)](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/oauth-quickstart-guide) _[documented s10,s11,s6]_

### 8. Install in a developer test account (10–20 min, you)

1. Go to Development > Projects, click your project, then click your app's UID in the component list.
2. On the Distribution tab, next to Test installs, click 'Add test install(s)'.
3. In the right panel, click Install next to your test account.
4. Review the permissions, select the checkbox to authorize installing an unverified app, then click 'Connect app'.
5. Confirm that your backend received the code and stored tokens, then run `hs project dev` for local development.

[Install in a developer test account](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app) _[documented s1]_

### 9. Private distribution: add approved accounts (5–15 min, you)

1. On the app's Distribution tab, click 'Add approved account(s)'.
2. Under 'Other production accounts', select the checkbox for each account (max 10), then click 'Save changes'.
3. Hover an approved account to copy its install link, and send that link to the customer's admin.

[Install a privately distributed OAuth app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) _[documented s3]_

### 10. Marketplace distribution: sign the AUP and get the install URL (10–20 min, you)

1. On the app's Distribution tab, click 'Begin publishing'.
2. Review and sign the Acceptable Use Policy. You can close the panel and return later via 'Continue publishing'.
3. Copy the sample install URL into your agent's 'Connect HubSpot' button. No allowlist applies, but installs cap at 25 until listed.
4. Tell early customers to expect an unverified-app warning. They must click 'Connect app', type 'I accept the risk', then click Connect.

[Install an OAuth marketplace app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) _[documented s3]_

### 11. Verify your domain to soften the install warning (15–60 min, agent prepares, you submit)

1. Go to Development > Domain and click 'Verify a domain'.
2. Enter your domain and click Next, then add the TXT record (Host (name) and Value) at your DNS provider and click Next.
3. Verification usually completes within an hour but can take up to 48 hours. Only one verified domain is allowed per developer account.

[Verified domains](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) _[documented s3]_

### 12. Create and submit the Marketplace listing (1–3 days, agent prepares, you submit)

1. Confirm you have 3 active, unaffiliated production installs with successful API calls in the last 30 days.
2. Go to Development and click 'App Listings' in the left sidebar. In the upper right, click 'Create listing', select your app and click Next, then choose the primary listing language and click Next.
3. Complete all seven tabs: Listing info, App details, Pricing, App features, Support info, Testing info, Review info. Since March 31, 2026 test credentials are no longer required; provide a demo video or walkthrough instead.
4. Make sure every URL is live and crawlable, and allowlist the 'HubSpot Crawler' user agent. Add an integration-specific setup guide, privacy policy and terms. Make Shared data match your scopes, marking objects with read+write scopes as bi-directional.
5. Submit. Only one app can be in review at a time, and extra submissions are auto-rejected. Expect initial feedback within 10 business days.

[Listing your app](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app) · [Listing requirements](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements) · [Setup guide requirements](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/create-an-app-listing-setup-guide) _[documented s16,s4]_

### 13. Apply for certification (optional, later) (1–3 days, agent prepares, you submit)

1. Wait until the app has been listed for 6+ months and has 60+ active installs. The 'Certify app' option only appears when you are eligible.
2. Record a demo video of at least 3 minutes (YouTube URL) covering install, setup, core use, disconnect and uninstall. Promotional videos are rejected.
3. Go to Development > App Listings, hover over the app, click More, then select 'Certify app'. Paste the video URL and click 'Submit certification application'.
4. Complete the OAuth token storage security questionnaire, and confirm the app uses the uninstall endpoint and a supported platform/API version.

[Applying for certification](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/apply-for-certification/applying-for-app-certification) · [Certification requirements](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/apply-for-certification/certification-requirements) _[documented s14]_

### 14. Alternative: create a service key for single-account access (5–15 min, you)

1. In your HubSpot account, go to Development > Keys > Service keys and click 'Create service key'.
2. Enter a name, click 'Add new scope', tick the scopes you need (use 'Find a scope' to search), click Update, then click Create and confirm.
3. Open the key, click Show, then Copy, and send it as a Bearer token. Optionally turn on Automatic rotation (every 3, 6 or 12 months).

[Service keys](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys) _[documented s13]_

## Blockers

- **Can't find 'Create app' / tutorial shows old Apps UI** (medium). Symptom: Older tutorials say to go to Apps > Create app > Auth tab and tick scopes. That button is missing, or creating a public app is blocked. Fix: Legacy public app creation was disabled on May 26, 2026 (new accounts) and June 23, 2026 (existing accounts). Use `hs project create` and configure auth in app-hsmeta.json instead. _[documented s7,s9]_
- **Installs stop at 25** (high). Symptom: New customers cannot install the marketplace-distribution app after the 25th account. Fix: Get 3 active installs and submit a Marketplace listing. The cap lifts automatically on approval. In the meantime, uninstall stale or internal portals; developer test accounts do not count. HubSpot reportedly does not raise the cap on request (community). _[documented s3,s5]_
- **AI connector listing rejected for account-level access** (high). Symptom: A reviewer flags that your app is an AI connector without user-level permissions or the HubSpot MCP server. Fix: Create a NEW app on platform 2026.09 with isUserLevel: true, or build on the HubSpot remote MCP server; account-level apps cannot be converted. Customers will need to reconnect. Decide this up front. _[documented s4,s12]_
- **Redirect URL rejected / redirect_uri mismatch** (medium). Symptom: An error on the authorize page, or token exchange fails for http://127.0.0.1 or a non-HTTPS URL. Fix: Use https in production and http://localhost (not 127.0.0.1) for local testing. Add the exact URL to auth.redirectUrls, run `hs project upload`, and send the same redirect_uri in the authorize and token calls. _[documented s10]_
- **Authorize page error about scopes / install fails on lower-tier portals** (medium). Symptom: Users see a scope error, or cannot install because their account lacks a tool such as an Enterprise-only feature. Fix: Make the scope parameter include every requiredScope. Move tier-dependent scopes to optionalScopes (passed as optional_scope) or conditionallyRequiredScopes, then check the granted scopes in the token. _[documented s2]_
- **Customer user cannot install the app** (low). Symptom: A customer user gets a permissions error when connecting. Fix: The installer must be a Super admin, or have the 'HubSpot Marketplace access' permission plus permissions matching your requested scopes. Ask the customer's admin to install. _[documented s3]_
- **Listing submission rejected or stuck in Draft** (medium). Symptom: Rejection for dead URLs, generic product copy, mismatched pricing, unused scopes or a second app submitted while one is in review. Fix: Allowlist 'HubSpot Crawler'. Write integration-specific copy and a setup guide. Match pricing to your site. Remove unused scopes. Submit one app at a time. _[documented s4]_
- **Listing rejected for unsupported platform version or OAuth v1** (high). Symptom: After Nov 2, 2026, the new listing is rejected because the app is legacy or on Projects 2023.2/2025.1, or uses /oauth/v1/token. Fix: Migrate to a supported platform version (2025.2, 2026.03, or the latest 2026.09) and switch to the date-based /oauth/<version>/token endpoints. _[documented s6]_
- **Expired access token (401) after 30 minutes** (low). Symptom: API calls start failing about 30 minutes after connect. Fix: Refresh with grant_type=refresh_token before expires_in elapses, and serialize refreshes per hub_id. _[documented s11]_

## Agent vs. you

**An agent can:**
- Run `npm install -g @hubspot/cli@latest`, `hs project create`, `hs project upload` and `hs project dev` once you have authenticated the CLI
- Write app-hsmeta.json: uid, distribution, auth.type, redirectUrls, requiredScopes/optionalScopes/conditionallyRequiredScopes, isUserLevel
- Audit your code's API calls and derive the minimal scope list, split into required and optional
- Implement the authorize URL, callback, token exchange against the date-based OAuth endpoint, per-hub_id token storage, 30-minute refresh and the uninstall endpoint
- Add the DNS TXT record for domain verification if it has DNS API access
- Draft the Marketplace listing copy, integration setup guide, Shared data table, pricing text and certification demo-video script

**You must:**
- Create the HubSpot developer account and developer test accounts, and log in
- Generate the personal access key for `hs account auth`
- Copy the client secret from the Auth tab into your secret store (and rotate it if exposed)
- Click through consent screens ('Connect app', 'I accept the risk') for test installs
- Sign the Acceptable Use Policy ('Begin publishing') and accept the Technology Partner Program Agreement
- Recruit the first 3 real, unaffiliated customer installs before listing
- Submit the listing, answer reviewer feedback, record the certification demo video and complete the security questionnaire

## What we couldn't confirm

- HubSpot publishes no turnaround time for certification review.
- Real-world listing approval times were not sampled from the community. The 2-10 week range is derived only from HubSpot's '10 business days' initial review and '60 days' feedback window.
- The Nov 2, 2026 listing rule names v2025.2 and v2026.03 as supported. That 2026.09 (the latest, needed for user-level access) is also accepted is inferred, not stated in that changelog.
- The exact token endpoint path differs across official pages (/oauth/2026-03/token in the May 2026 changelog vs /oauth/2026-09/token on the latest token docs). Use whichever version your platform/API version supports.
- Refresh-token lifetime (whether refresh tokens expire on their own) was not stated on the pages reviewed.
- The 'Solutions Partner: 100 private installs' override comes from the Sept 2025 changelog. The current Manage apps page states only 10.
- Console URL paths under app.hubspot.com (developer projects, app listings) were not confirmed, so pointer urlPatterns match any app.hubspot.com page (including EU app-eu1). No console walkthrough was done.
- Whether HubSpot ever grants exceptions to the 25-install cap is community-reported only.
- What exactly counts as an 'AI connector' for the user-level/MCP rule is decided by HubSpot reviewers.

## Verification log

- 2026-10-30 · doc-review · **corrected**: Is creating a public app in the developer account UI (Apps > Create app) still the way to start?. No. The Apr 23, 2026 changelog disabled legacy public app creation from May 26, 2026 (new accounts) and June 23, 2026 (existing accounts). New apps must be CLI projects (`hs project create`). Legacy public apps go unsupported, with enforcement in September 2027.
- 2026-10-30 · doc-review · **confirmed**: Install limit for unlisted public apps (commonly cited as 25). Confirmed: 25 installs for marketplace-distribution OAuth apps before listing, excluding developer test accounts (Manage apps page). It is enforced for apps created on or migrated to 2025.2+ since Sept 22, 2025. Private distribution allows 10 allowlisted accounts, and static/service keys are single-account.
- 2026-10-30 · doc-review · **confirmed**: Minimum installs required before a Marketplace listing. 3 active, unique installs from unaffiliated production accounts with successful activity in the past 30 days. Listing review: initial review within 10 business days, and the whole process no more than 60 days from feedback.
- 2026-10-30 · doc-review · **corrected**: Can AI-agent apps list with ordinary account-level OAuth?. The listing requirements (last modified Oct 15, 2026) say AI connectors must use user-level access or HubSpot's MCP server. User-level needs platform 2026.09, cannot be retrofitted onto account-level apps, and drops webhooks, app cards, serverless functions and workflow actions.
- 2026-10-30 · doc-review · **corrected**: Private app as the single-portal alternative. Advice to 'just create a private app in Settings > Integrations > Private Apps' is outdated. Legacy private app creation was disabled Sept 28, 2026 (new accounts) and Oct 26, 2026 (existing accounts). HubSpot now points to Service Keys (Development > Keys > Service keys) or static-auth project apps.
- 2026-10-30 · doc-review · **corrected**: OAuth token endpoint for new listings. Most tutorials use POST https://api.hubapi.com/oauth/v1/token. The May 7, 2026 changelog requires the date-based OAuth v3 endpoints for new listings and certifications and says v1 is being deprecated. The latest docs show /oauth/2026-09/token.
- 2026-10-30 · doc-review · **confirmed**: Access token lifetime. expires_in is 1800 seconds (30 minutes) in the official quickstart and token examples, and in HubSpot's developer blog.
- 2026-10-30 · doc-review · **confirmed**: Redirect URL rules. HTTPS is required, http://localhost is allowed for testing, and IP addresses are not supported. URLs are configured in app-hsmeta.json redirectUrls and shown at the bottom of the Auth tab.
- 2026-10-30 · doc-review · **corrected**: Test credentials required in listing submissions. Since March 31, 2026, test credentials are no longer required for listing submissions. Demo videos or guided walkthroughs replace them, although the wizard still has a 'Testing info' tab.
- 2026-10-30 · doc-review · **unverifiable**: Certification review timeline. The certification pages list eligibility (6 months listed, 60 active installs, demo video of at least 3 minutes) but give no review duration.
- 2026-10-30 · http-probe · **confirmed**: Automated: developer console (https://app.hubspot.com/developer). Loaded: "Developers | HubSpot".
- 2026-10-30 · http-probe · **confirmed**: Automated: authorize endpoint with a fake client_id (https://app.hubspot.com/oauth/authorize). Endpoint answered HTTP 200 ("HubSpot OAuth").
- 2026-10-30 · doc-review · **confirmed**: Automated: 43 quotes re-fetched and matched against their cited pages. 43 of 43 quotes found verbatim in the live page HTML.  17/18 source URLs returned HTTP 200.

## Sources

- s1: [Create a new app using the CLI](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/create-an-app) (official-docs, accessed 2026-10-30)
- s2: [App configuration](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration) (official-docs, accessed 2026-10-30)
- s3: [Manage apps in HubSpot](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot) (official-docs, accessed 2026-10-30)
- s4: [App listing requirements in the HubSpot Marketplace](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/app-marketplace-listing-requirements) (official-policy, accessed 2026-10-30)
- s5: [New marketplace distribution app install limits (changelog)](https://developers.hubspot.com/changelog/new-marketplace-distribution-app-install-limits) (official-blog, accessed 2026-10-30)
- s6: [App Listing and App Certification Requirement Updates for May 2026 (changelog)](https://developers.hubspot.com/changelog/app-listing-and-app-certification-requirement-updates-for-may-2026) (official-blog, accessed 2026-10-30)
- s7: [Legacy Public App Creation Sunset (changelog)](https://developers.hubspot.com/changelog/legacy-public-app-creation-sunset) (official-blog, accessed 2026-10-30)
- s8: [Legacy Private App Creation Being Disabled (changelog)](https://developers.hubspot.com/changelog/legacy-private-app-creation-sunset) (official-blog, accessed 2026-10-30)
- s9: [Legacy APIs and Apps: What's Going Unsupported and When (changelog)](https://developers.hubspot.com/changelog/legacy-apis-and-legacy-apps-whats-going-unsupported-and-when) (official-blog, accessed 2026-10-30)
- s10: [Working with OAuth](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth) (official-docs, accessed 2026-10-30)
- s11: [Production-Ready OAuth Token Management for HubSpot Integrations](https://developers.hubspot.com/blog/oauth-token-management-hubspot-integrations) (official-blog, accessed 2026-10-30)
- s12: [Configure user-level access for an app](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/user-level-apps) (official-docs, accessed 2026-10-30)
- s13: [Make API requests using a service key](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/account-service-keys) (official-docs, accessed 2026-10-30)
- s14: [Applying for app certification](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/apply-for-certification/applying-for-app-certification) (official-docs, accessed 2026-10-30)
- s15: [Developer platform and API versioning](https://developers.hubspot.com/docs/developer-tooling/platform/versioning) (official-docs, accessed 2026-10-30)
- s16: [HubSpot Marketplace | Listing your app](https://developers.hubspot.com/docs/apps/developer-platform/list-apps/listing-your-app/listing-your-app) (official-docs, accessed 2026-10-30)
- s17: [Determine your migration path](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/migrate-an-app/overview) (official-docs, accessed 2026-10-30)
- s18: [New Marketplace Distribution App Install Limits (community thread)](https://community.hubspot.com/t/new-marketplace-distribution-app-install-limits/139886) (community, accessed 2026-10-30)
- p1: [Live probe (console): Loaded: "Developers | HubSpot".](https://app.hubspot.com/developer) (probe, accessed 2026-10-30)
- p2: [Live probe (authorize-endpoint): Endpoint answered HTTP 200 ("HubSpot OAuth").](https://app.hubspot.com/oauth/authorize) (probe, accessed 2026-10-30)

Evidence tags: tested = exercised live; documented = official source, quote checked; inferred = reasoning; unverified = unconfirmed.