Using Date-based API 2025-09

[VideonisseDev]

I'm new to HS but has setup a developer account and a public test project with Oauth2. I test the API using Postman and to have latest features I use the Date-based API version "2025-09".

But I have a problem with the Scopes used for the Oauth2.

When I use GET /crm/objects/2025-09/, for Companies and Deals, I get an error:

"One or more of the following scopes are required."

"requiredGranularScopes":
"crm.schemas.deals.read",
"crm.objects.deals.sensitive.read.v2",
"crm.objects.deals.read",
"crm.objects.deals.highly_sensitive.read.v2"

HOWEVER, when I try to include them as optional scopes in my "app-hsmeta.json" I get error message when I try to Deploy the new build:

"The scope crm.objects.companies.sensitive.read.v2 could not be recognized."

What is the cause of the problems here? Do I need to apply to a beta program to use the specific API and why are some of the new v2 scopes not valid when deploying the project?

[GRajput · Accepted solution]

Hi @VideonisseDev 

You can create a private app and provide the required scopes there. It will be a better approach for you to test the API and later use it in a project.


Thanks!

[suprdense]

Hey @VideonisseDev ,

The v2 scopes shown in your error messages aren’t actual OAuth scopes they’re internal identifiers tied to HubSpot’s new date-based API versions. The OAuth system still recognizes only the canonical scope names (the same ones without .v2). When you try to include .v2 variants in your manifest, HubSpot rejects them because they don’t exist in the public scope registry.

These .v2 labels appear only in API responses to indicate versioned access paths, not scopes you can request. So if you see something like crm.objects.deals.sensitive.read.v2, you should simply use crm.objects.deals.sensitive.read instead.

For access: private apps can use sensitive scopes immediately within your account. Public apps, however, need approval, HubSpot’s Ecosystem Quality team must allowlist those sensitive or highly sensitive scopes before your app can go live.

In short, the fix is simple: remove .v2, redeploy, reauthorize, and request allowlisting if your app is public.

I hope this helps clear things up! If this solution works for you, please consider marking it as “Accepted” and giving it an upvote - it’ll make it easier for other community members to find and benefit from it too.

[VideonisseDev]

Hi @suprdense, 

Thanks for the answer. Unfortunatly, it did not quite solve the issue. What do I need to use the new date-based API versions?

So far I understand:

1. I need OAuth2 for authorization
2. To set up OAuth2 I must create the basics for a Public app (Marketplace).
3. But I still cannot use some of the endpoints, because I must have the sensitive scopes activated in my OAuth2 config. (for example GET /crm/objects/2025-09/, for Companies and Deals)
4. To solve this I must contact the "HubSpot’s Ecosystem Quality team".
5. However, I have not created an app yet, I just want to test the new api.

I suppose I have missed some guidelines regarding using OAuth2 with HubSpot APIs, because this is a little confusing for me as a new user to HubSpot.

[chighsmith]

Hi @VideonisseDev,

Thank you for posting to the Community!

I understand that you’re encountering issues with unavailable granular OAuth2 scopes when using the latest date-based HubSpot API version (“2025-09”), and you’re unsure whether special access or enrollment in a beta program is required, or why some new v2 scopes cannot be added to your project.

I'd like to tag in some of our Top Contributors to see if they have experienced this behavior before -- Hi @GiantFocal @AdamLPW and @HubSpotMaster I hope you all are having a wonderful Tuesday! Have any of you seen this error before? If so, how did you resolve? Do you have any advice for @VideonisseDev?

Thank you!

Cassie, Community Manager