Jira cloud rest api integration through Oauth-2-3LO

Jira Development Jira Cloud
, , , , ,
1

I was going through the docs here → https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/
For generating the authorization url, with several scopes, how to know which scopes to add and which to leave. Also, how to add several multiple scopes in my url itself?

2

Welcome to the Atlassian developer community @SahilAnower,

These scopes are used in multiple contexts, both for normal OAuth flows and for Forge apps, which hide the OAuth flow but still rely on apps enumerating scopes. Hence, the instructions for generating the OAuth authorization url are on a page dedicated to OAuth.

When trying to figure out which scopes you’ll need, you’ll want to start from the REST APIs your client would use. For example, if you want to get an issue using GET /rest/api/3/issue/{issueIdOrKey}, then you’ll notice a section explains which scopes are necessary.

Either use a simple, single scope:

Classic: read:jira-work

Or use the newer and more fine-grained scopes:

Granular: read:issue-meta:jira, read:issue-security-level:jira, read:issue.vote:jira, read:issue.changelog:jira, read:avatar:jira, read:issue:jira, read:status:jira, read:user:jira, read:field-configuration:jira

You might ask, why would I ever choose more scopes? The short (but oversimplified) answer is that it starts to make sense as you use multiple endpoints.

For the sake of illustration, lets say you did choose granular scopes and now you are trying to construct the authorization URL. The docs already explain:

scope: (required) Set this to the desired scopes:

  • Separate multiple scopes with a space.
  • Only choose from the scopes that you have already added to the APIs for your app in the developer console.
  • You may specify scopes from multiple products.

So our string of scopes would be:

read:issue-meta:jira read:issue-security-level:jira read:issue.vote:jira read:issue.changelog:jira read:avatar:jira read:issue:jira read:status:jira read:user:jira read:field-configuration:jira

But, that’s going to be a query parameter, so when it is expressed in the URL, it will look more like this:

https://auth.atlassian.com/authorize?scope=read:issue-meta:jira%20read:issue-security-level:jira%20read:issue.vote:jira%20read:issue.changelog:jira%20read:avatar:jira%20read:issue:jira%20read:status:jira%20read:user:jira%20read:field-configuration:jira&...

Notice the space encoded as %20. More parameters would follow in the URL as specified in the docs.

There’s a lot of helpful utility in the developer console that will help you work through this, including a generated URL with the scopes you picked for your app (don’t forget to replace the client ID with your own).

3

Thanks a lot for such broad explanation. I would ask more when I am in need!
Thanks again!

4

Also, can you clarify this small issue, that if I add classic scopes in url, does it cover all underneath granular scopes as well or not?

5

@SahilAnower,

I wish it were that simple. For the case of that single issue endpoint, yes. You can use the classic scope and it covers all the granular scopes. But, over a set of multiple endpoints and their scopes, I’m not sure the mapping is so simple.

To help you decide which to use, a short history lesson is required. Atlassian is trying to move to more fine-grained scopes. But, in rolling out the new scopes we discovered a number of problems and the rollout has been paused. In my personal estimation (not an official statement or informed by internal engineering), any path forward is likely to require a new set of scopes (probably using a lot of the granular scopes, but not 100% compatible), which means that neither classic nor granular scopes are future proof. Therefore, my recommendation is to use the simplest thing that could possibly work. If that’s classic scopes for you, use them. As it happens, that is how the classic scopes are current “tagged” in the REST API docs (as recommended).

Sorry for all the nuance but these details can be important to the kinds of design decisions you are trying to make.

6

I just want the details (Read) related to the Dashboard of Jira Main:

  1. Sprint
  2. Issues
  3. Backlog
  4. Board
    Can you please let me know what would be the scopes that I need to add to the url for the above mentioned scopes?
7

@SahilAnower,

I’ve already pointed you to the section for issues. The remaining scopes can be found in the Jira Software Cloud REST API.