How do I enable OAuth authentication for the conversations API in HubSpot?

Developer Support APIs & Integrations
1

I need to get access to the Conversations API, but first I seem unable to get a auth token for any scope.
I created an app, saved the client id and secret, and then followed the instructions here: GitHub - HubSpot/oauth-quickstart-nodejs: A Node JS app to get up and running with the HubSpot API using OAuth 2.0 · GitHub
I configured the app, entering the client id and secret, and ran it. It asked for a login. After login I got this error.

Couldn’t complete the connection

An error occurred while validating the app authorization.
The same error appears when trying to use Postman or the browser.
The url looks kind of like this: https://app.hubspot.com/oauth/authorize?client_id=blah-blah&scope=crm.objects.contacts.read&redirect_uri=http:\\localhost:3000\auth-callback
What steps have I missed? Is there something else I need to do to enable oauth for that client id?

2

What works for me is changing:

“distribution”: “private”
to
“distribution”:marketplace in app-hsmeta.json.
Then after adding the scopes, I can access the API. But I’m not sure if this is the way to do it. I don’t want to distribute this publicly.

The directions here Legacy public apps - HubSpot docs seem out of date. I don’t see a create app button.

3

Hi @ANiazov and thanks for getting back to us!
Based on the documentation, changing “distribution”: “marketplace” in your app-hsmeta.json is the correct approach for OAuth apps.
Here’s what you need to know, for OAuth apps:

- “distribution”: “marketplace” allows installation in multiple accounts (up to 25 before listing, unlimited after marketplace approval)
- “distribution”: “private” limits installation to up to 10 allowlisted accounts
You don’t need to distribute publicly. Setting “distribution”: “marketplace” doesn’t automatically list your app on the marketplace.
According to the docs, you can sign the Acceptable Use Policy (AUP) and use the install URL without creating a marketplace listing.
This gives you OAuth functionality while keeping the app unlisted.

Regarding your question about “Public apps”, I’d recommend using the CLI and configuration files instead of the UI-based “Create app” button.
And here are some documentation for reference:
- Install the HubSpot CLI
- App configuration
- Manage apps in HubSpot
- Working with OAuth
I hope this helps!
Have a lovely day!
Bérangère

4

Hi @ANiazov

It sounds like you’ve set up everything correctly and generated the installation URL, but the install isn’t completing. This usually happens if you don’t have all the permissions the app requires. Ask a super admin to install it, or try with a test account. If the issue persists, please share a screenshot.

I hope this will help you out. Please mark it as Solution Accepted and upvote to help another Community member.

Thanks!

5

Hi @ANiazov

Good call catching that, the confusion comes from HubSpot’s newer Developer Projects flow.

When “distribution”: “private” is set, OAuth installs are limited to allowlisted portals, so any non-listed account will throw the “validating authorization” error you saw. Changing it to “marketplace” simply enables OAuth installs beyond that list, without forcing a public listing. It’s the right move for internal or partner use cases that need OAuth but aren’t meant for marketplace exposure (Working with OAuth | OAuth Quickstart Guide - HubSpot docs )

Also make sure your scopes include conversations.read or conversations.write depending on which endpoints you’re calling; the Conversations API is separate from the CRM scopes. After updating scopes, run hs project upload and regenerate your install URL to refresh tokens. If this project later needs to sync conversation data back to CRMs or data warehouses, Stacksync can handle the two-way mapping automatically so you don’t juggle tokens or endpoints yourself.