Jira Cloud OAuth 2.0 – JQL API works but granular scopes not reflected

[Rohit Thakur]

Hi Community,

We are migrating from the deprecated /rest/api/3/search endpoint (Basic Auth + API token) to the new /rest/api/3/jql/search endpoint which requires OAuth 2.0 granular scopes.

Here’s what we’ve done so far:

• Created an OAuth 2.0 (3LO) app in the Atlassian developer console.

• Requested granular scopes:

  • read:jql:jira

  • validate:jql:jira

• Completed the consent flow using the authorization URL with these scopes.

• Successfully exchanged the code for an access token.

When decoding the access token, we do see:

"scope": "read:jql:jira validate:jql:jira"

However, when we try to call the JQL endpoint:

POST https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/jql/search Authorization: Bearer <access_token> Content-Type: application/json { "queries": [ { "query": "project = TEST AND created >= -7d", "maxResults": 5, "fields": ["key", "summary", "status"] } ] }

We still get this error:

{"code":401,"message":"Unauthorized; scope does not match"} 

---

Questions:

1. Are read:jql:jira and validate:jql:jira the correct scopes for using the new JQL API?

2. Should we remove legacy scopes (like read:jira-work) completely and only use granular scopes?

3. Why does the token show the correct scopes but the request still fails with Unauthorized; scope does not match?

4. Is there any migration guidance specific to JQL and granular scopes beyond the changelog note (CHANGE-2046)?

[Marc - Devoteam]

Hi @Rohit Thakur 

Welcome to the community.

All scopes mentioned in the API endpoint are required. 

So all these are needed:

• read:jira-work
• read:issue-details:jira
• read:audit-log:jira
• read:avatar:jira
• read:field-configuration:jira
• read:issue-meta:jira

[Rohit Thakur]

@Marc - Devoteam So, should we use a mixture of granular and legacy scopes?

[Marc - Devoteam]

Hi @Rohit Thakur 

Yes, according to the API documentation.