Frequently Asked Questions

• What happens if a user grants access to more than one Atlassian site for an app?
• What is the state parameter used for?
• How do I retrieve the public profile of the authenticated user?
• Is CORS whitelisting supported?

What happens if a user grants access to more than one Atlassian site for an app?

Only one grant exists per app for a given Atlassian account. If a user grants access to more than one Atlassian site for this app, then the additional sites are added to the same grant. This means that existing access tokens will give you access to all sites and scopes that a user has granted your app access to.

What is the state parameter used for?

The primary use for the state parameter is to associate a user with an authorization flow. This makes the authorization flow more secure, as the authorization flow cannot be hijacked to associate a user's account with another user's token. Consider the following example scenario using Jira:

1. An application, named Incidents_Application, has a Jira integration that implements OAuth 2.0 authorization code grants but does not specify a state parameter.
2. A malicious actor, Mallory, initiates a Jira authorization flow for herself. This could be via the Incidents_Application or by crafting an authorization URL that includes the Incidents_Application's client_id.
3. Mallory blocks the request to the Incidents_Application's callback URL during the authorization flow. She records the URL, including the code parameter.
4. Mallory tricks another user, Edward, into visiting the callback URL in his browser.
5. The Incidents_Application handles the callback and exchanges Mallory's code for an access token to Jira. Edward is logged into the Incidents_Application and the callback request came from Edward's browser, so Mallory's token is now linked to Edward's account.
6. Mallory now has access to information sent to Edward by the Incidents_Application via the Jira integration. For example, the Incidents_Application may create a Jira ticket about a confidential incident, where the ticket is intended to be restricted to Edward but is restricted to Mallory instead.

If the Incidents_Application integration had used a state parameter, the Incidents_Application would have known that the callback URL belonged to Mallory and ignored the request.

Other uses for the state parameter include:

• Acting as a key for keeping track of specific details about the flow.
• Returning the user to the right step in their workflow after sending them through the authorization flow.

How do I retrieve the public profile of the authenticated user?

The User Identity API is used to retrieve the public profile of the authenticated user. If you want to use this API, do the following:

• Add the User Identity API to your app in the developer console.
• Add the read:me scope to the authorization URL for your app.

An example of a request to retrieve the public profile of the authenticated user is shown below:

1
2
curl --request GET \
  --url https://api.atlassian.com/me \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

Example response:

1
2
{
  "account_type": "atlassian",
  "account_id": "112233aa-bb11-cc22-33dd-445566abcabc",
  "email": "mia@example.com",
  "name": "Mia Krystof",
  "picture": "https://avatar-management--avatars.us-west-2.prod.public.atl-paas.net/112233aa-bb11-cc22-33dd-445566abcabc/1234abcd-9876-54aa-33aa-1234dfsade9487ds",
  "account_status": "active",
  "nickname": "mkrystof",
  "zoneinfo": "Australia/Sydney",
  "locale": "en-US",
  "extended_profile": {
    "job_title": "Designer",
    "organization": "mia@example.com",
    "department": "Design team",
    "location": "Sydney"
  }
}

Is CORS whitelisting supported?

CORS whitelisting is supported for api.atlassian.com. CORS whitelisting allows OAuth 2.0 authorization code grants to work for browser-based XHR or fetch requests subject to cross-origin restrictions, such as Chrome or Electron apps.