HubSpot OAuth Redirect URL and Scopes Checklist

Start by deciding whether the app is truly OAuth-based. HubSpot's create-app docs distinguish OAuth from static authentication, and the Marketplace requirements add an important boundary for Marketplace apps: OAuth is required and scopes should be limited to what the app needs.

For OAuth apps, inspect `app-hsmeta.json` for redirect URLs and auth configuration before upload. Redirect URLs should match the backend OAuth server and the environment being tested. If a URL points to local development, staging, or production, label that clearly so a reviewer does not confuse a test callback with a final callback.

For privately distributed static-auth apps, do not keep OAuth assumptions in the handoff. The create-app docs state that if static authentication is chosen for a privately distributed app, the `redirectUrls` sub-property should be removed from the `auth` field. That is a concrete source-linked distinction worth exposing in any agent prompt.

Scopes are not just technical fields. They shape install consent, Marketplace review, and user trust. HubSpot's Marketplace requirements say to request only scopes the app needs, and they connect shared-data information to the scopes requested by the app.

Build a scope table with four columns: requested scope, app feature that uses it, read/write behavior, and where the user-facing listing explains the data flow. If a requested scope has no implemented feature or no listing explanation, either remove it or document why it is conditional or optional according to current requirements.

Avoid vague phrases such as 'full CRM access' unless the app truly needs and explains that scope pattern. The safer long-tail SEO answer is: make scopes least-privilege, implemented, and reflected in listing/shared-data claims.

After upload, OAuth apps need backend credentials and an install flow that can be tested. The create-app docs describe configuring client ID and client secret in the backend OAuth server after project upload for OAuth apps. If that step is missing, the project can exist in HubSpot while the install flow is still incomplete.

Test the install in the right account type and record the result. A good install note includes redirect URL used, scopes displayed, account installed into, backend environment, success/failure result, and any error text. That note is valuable for debugging and for Marketplace readiness reviews.

Keep Marketplace submission separate from install success. A working install flow is necessary work, but Marketplace review also evaluates listing materials, policies, support, shared data, and other requirements. This guide is designed to organize the work, not certify the outcome.