OAuth 2.0 (3LO) apps

This page shows you how to configure OAuth 2.0 (3LO) (also known as "three-legged OAuth" or "authorization code grants") apps. OAuth 2.0 (3LO) allows external applications and services to access Atlassian product APIs on a user's behalf. OAuth 2.0 (3LO) apps are created and managed in the developer console.

Overview

OAuth 2.0 (3LO) involves three parties:

• An Atlassian site (resource)
• A user (resource owner)
• An external application/service (client).

For example, a Jira or Confluence site (resource), an Atlassian user (resource owner), and Gmail (client). Underlying the authorization interactions between these three parties is an authorization server.

To the user, the authorization process looks like this:

1. The app directs the user to an Atlassian screen that prompts them to grant access to their data on the Atlassian site. The screen displays the access being requested in the Atlassian product.
2. The user grants (or denies) access to their data on the Atlassian site, via the screen.
3. The user is directed back to the external service. If the user granted access, the external service can now access data (within the specified scopes) from the Atlassian site on the user's behalf.

Underlying this process are a number of interactions between the external service, the app, and the authorization server. The full process is described in more detail below.

Note, this process assumes that the external service has registered an app with Atlassian that can use OAuth 2.0 (3LO).

1. The user, in the external service, uses a feature that requires data from an Atlassian product.
2. The external service seeks authorization to access the product's APIs, within the specified scopes, on behalf of the user.
3. The user is directed to the Atlassian account login screen, if they are not already logged in, and prompted to log in.
4. The user is directed to the authorization URL for the authorization server. This displays a screen that prompts the user to grant access to their data.
5. If the user grants access, the user is directed to the callback URL with an authorization code.
6. The app makes a POST to the token URL for the authorization server, exchanging the authorization code for an access token.
7. The access token can now be used to access the APIs for the authorized Atlassian site on behalf of the user. This can be used until the token expires or is revoked.

Enabling OAuth 2.0 (3LO)

Before you can implement OAuth 2.0 (3LO) for your app, you need to enable it for your app using the developer console.

1. From any page on developer.atlassian.com, select your profile icon in the top-right corner, and from the dropdown, select Developer console.
2. Select your app from the list (or create one if you don't already have one).
3. Select Authorization in the left menu.
4. Next to OAuth 2.0 (3LO), select Configure.
5. Enter the Callback URL. Set this to any URL that is accessible by the app. When you implement OAuth 2.0 (3LO) in your app (see next section), the redirect_uri must match this URL.
6. Click Save changes.

Note, if you haven't already added an API to your app, you should do this now:

1. Select Permissions in the left menu.
2. Next to the API you want to add, select Add.

Implementing OAuth 2.0 (3LO)

Once you have enabled OAuth 2.0 (3LO) for your app, you can implement it in your app's code. There are a number of key parts to this:

1. Direct the user to the authorization URL to get an authorization code
2. Exchange the authorization code for an access token
3. Authorize any calls to the product APIs using the access token
4. Check site access for the app

1. Direct the user to the authorization URL to get an authorization code

As described in the Overview above, your app should start the authorization flow by directing the user to the authorization URL:

1
2
3
4
5
6
7
8

https://auth.atlassian.com/authorize?
  audience=api.atlassian.com&
  client_id=YOUR_CLIENT_ID&
  scope=REQUESTED_SCOPE_ONE%20REQUESTED_SCOPE_TWO&
  redirect_uri=https://YOUR_APP_CALLBACK_URL&
  state=YOUR_USER_BOUND_VALUE&
  response_type=code&
  prompt=consent

Use the authorization URL in a GET request. You can get this URL by going to your app in the developer console, selecting Authorization in the left menu, and selecting Configure next to OAuth 2.0 (3LO). Alternatively, you can construct the URL manually (for example, if you want to specify scopes from multiple products).

The query parameters for the authorization URL are described below:

• audience: (required) Set this to api.atlassian.com.
• client_id: (required) Set this to the Client ID for your app. Find this in Settings for your app in the developer console.
• 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.
• redirect_uri: (required) Set this to the callback URL configured in Authorization for your app in the developer console.
• state: (required for security) Set this to a value that is associated with the user you are directing to the authorization URL, for example, a hash of the user's session ID. Make sure that this is a value that cannot be guessed. You may be able to generate and validate this value automatically, if you are using an OAuth 2.0 client library or an authentication library with OAuth 2.0 support. For more information, including why this parameter is required for security, see What is the state parameter used for? below.
• response_type: (required) Set to code as you are requesting an authorization code (not a token).
• prompt: (required) Set to consent so that the screen prompting the user to grant access will display.

If successful, the user will be redirected to the app's callback URL, with an authorization code provided as a query parameter called code. This code can be exchanged for an access token, as described in step 2.

Determining the required scopes for an API operation

To find out which scope is required for an operation, check the OAuth scopes required field for the operation in the documentation for the API:

• Jira platform REST API documentation
• Jira Service Management REST API documentation
• Confluence REST API documentation

If the operation has the statement Apps can't access this REST resource, you can't use it with OAuth 2.0 (3LO).

Note that an app will always be constrained by the permissions of the user that an app is acting for, regardless of its scopes. For example, if a Jira app has the manage:jira-configuration scope but user does not have the Administer Jira permission, then the app will not be able to take Jira administration actions.

2. Exchange authorization code for access token

1
2
3
4

curl --request POST \
  --url 'https://auth.atlassian.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{"grant_type": "authorization_code","client_id": "YOUR_CLIENT_ID","client_secret": "YOUR_CLIENT_SECRET","code": "YOUR_AUTHORIZATION_CODE","redirect_uri": "https://YOUR_APP_CALLBACK_URL"}'

• client_id: (required) Set this to the Client ID for your app. Find this in Settings for your app in the developer console.
• client_secret: (required) Set this to the Secret for your app. Find this in Settings for your app in the developer console.
• code: (required) Set this to the authorization code received from the initial authorize call (described above).
• redirect_uri: (required) Set this to the callback URL configured for your app in the developer console.

If successful, this call returns an access token similar to this:

1
2
3
4
5
6
7
8

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <string>,
  "expires_in": <expiry time of access_token in second>,
  "scope": <string>
}

This access token can be used to make API calls, as described below.

3. Make calls to the API using the access token

Your app now has an access token that it can use to authorize requests to the APIs for the Atlassian site. To make requests, do the following:

1. Get the cloudid for your site.
2. Construct the request URL using the cloudid.
3. Call the API, using the access token and request URL.

3.1 Get the cloudid for your site

Make a GET request to https://api.atlassian.com/oauth/token/accessible-resources passing the access token as a bearer token in the header of the request. For example:

1
2
3
4

curl --request GET \
  --url https://api.atlassian.com/oauth/token/accessible-resources \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

This will retrieve the sites that have scopes granted by the token (see Check site access for the app below for details). Find your site in the response and copy the id. This is the cloudid for your site.

Here's a few example responses:

• A Jira site:

1
2
3
4
5
6
7
8
9
10
11
12
13

[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user",
      "manage:jira-configuration"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

• A Jira Service Management site:

1
2
3
4
5
6
7
8
9
10
11
12
13

[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user",
      "read:servicedesk-request"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

• A Confluence site:

1
2
3
4
5
6
7
8
9
10
11
12
13

[
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name",
    "url": "https://your-domain.atlassian.net",
    "scopes": [
      "write:confluence-content",
      "read:confluence-content.all",
      "manage:confluence-configuration"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

3.2 Construct the request URL

Requests that use OAuth 2.0 (3LO) are made via api.atlassian.com (not https://your-domain.atlassian.net). Construct your request URL using the following structure:

• Jira apps: https://api.atlassian.com/ex/jira/{cloudid}/{api}
• Confluence apps: https://api.atlassian.com/ex/confluence/{cloudid}/{api}

where:

• {cloudid} is the cloudid for your site that you obtained in the previous step. For example, 11223344-a1b2-3b33-c444-def123456789.
• {api} is the base path and name of the API. For example:
  • /rest/api/2/project for the project endpoint in the Jira REST API.
  • /rest/servicedeskapi/request for the request endpoint in the Jira Service Management REST API.
  • /rest/api/space for the space endpoint in the Confluence REST API.

Your request URL should look something like this (using the example cloudid and Jira API above):

https://api.atlassian.com/ex/jira/11223344-a1b2-3b33-c444-def123456789/rest/api/2/project

Note that if you are copying the examples in the API documentation, you will need to amend the example URLs as they currently use https://your-domain.atlassian.net/{api} rather than the request URLs shown above.

3.3 Call the API

Make the API call passing the access token as a bearer token in the header of the request. This will authorize the request on the user's behalf.

1
2
3
4

curl --request GET \
  --url <request URL> \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Accept: application/json'

For example:

1
2
3
4

curl --request GET \
  --url https://api.atlassian.com/ex/jira/11223344-a1b2-3b33-c444-def123456789/rest/api/2/project \
  --header 'Authorization: Bearer aBCxYz654123' \
  --header 'Accept: application/json'

4. Check site access for the app

An authorization grant is when a user consents to your app accessing a specific site and APIs within that site (via scopes). This can change when either of the following occur:

• The user revokes the grant for the site.
• The user consents to a new grant for the site. The scopes in the new grant override the scopes in the existing grant.

Therefore, since a grant can change over time, it's important that you check your app's access to a site and its APIs when calling the site's APIs. To check this, call the accessible-resources endpoint on https://auth.atlassian.com (you used this endpoint in a previous step to get the cloudid for your site). The endpoint is described in detail below:

Get list of resources

GET /oauth/token/accessible-resources

Request

Request parameters: None

Example:

1
2

curl --header 'Authorization: Bearer <access_token>' \
  --url 'https://api.atlassian.com/oauth/token/accessible-resources'

Response

200 OK example (Jira):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

[
  {
    "id": "8594f221-9797-5f78-1fa4-485e198d7cd0",
    "name": "Site name 2",
    "url": "https://your-domain2.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/koala.png"
  },
  {
    "id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
    "name": "Site name 1",
    "url": "https://your-domain1.atlassian.net",
    "scopes": [
      "write:jira-work",
      "read:jira-user",
      "manage:jira-configuration"
    ],
    "avatarUrl": "https:\/\/site-admin-avatar-cdn.prod.public.atl-paas.net\/avatars\/240\/flag.png"
  }
]

Each item in the response describes a container (for example, a Jira site) that your app has access to, the scopes associated with that access, and metadata such as the name and avatar URL (if any). It's important to understand that this endpoint won't tell you anything about the user's permissions, which may limit the resources that your app can access via the site's APIs.

Note, the id is not unique across containers (that is, two entries in the results can have the same id), so you may need to infer the type of container from its scopes.

Managing your OAuth 2.0 (3LO) apps

You can securely manage all your OAuth 2.0 (3LO) and Forge apps in one place using the Atlassian developer console. The console lets you view information about your apps, including their environments and scopes.

To access the console:

1. From any page on developer.atlassian.com, select your profile icon in the top-right corner.
2. From the dropdown, select Developer console.

Your existing OAuth 2.0 (3LO) and Forge apps are listed in the order they were created. OAuth 2.0 (3LO) apps are displayed with a 3LO lozenge.

The following details are listed:

• App name: the name of your app
• Distribution status:
  • Sharing: your app can be shared via link
  • Not sharing: your app can't be shared via link
• Updated on: the time and date you created your app or updated its settings

You can search for an app using the search bar above the app table.

View app details

Select any app on the My apps page to get more information about the app, including app ID, description, authorization, and permissions.

The Overview page displays the following panels:

• App details
  • App ID: the identifier for your app
  • Description: the description of your app
• Distribution
  • Distribution status: whether your app can be used by others
• Permissions
  • API scopes: which scopes are currently defined in your app
• Authorization
  • Authorization type: the authorization configured for your app

Select Settings in the left menu to view your app's authentication details, or to change your app's name, description, or avatar.

View app permissions

You can view the level of access your Forge app has to an Atlassian user's account by selecting Permissions in the left menu, or selecting the Permissions panel.

The Permissions page lists the APIs included in your app.

To add or remove individual scopes for an API, select Configure, and in the list of scopes, select Add or Remove. Note that users who previously consented to the scopes will need to re-consent to the new scopes.

Delete your app

You can only delete an app if it's not installed anywhere.

1. If your app is currently installed on a site, uninstall it.
2. Select Settings in the left menu, and select Delete app.

Distributing your OAuth 2.0 (3LO) apps

When you create an OAuth 2.0 (3LO) app, it's private by default. This means that only you can install and use it. If you want to distribute your app to other users, you must enable sharing.

1. Go to the Marketplace Support Service Desk and create a ticket.
2. Wait until your ticket is approved.
3. From any page on developer.atlassian.com, select your profile icon in the top-right corner, and from the dropdown, select Developer console.
4. Select your app from the list.
5. Select Distribution in the left menu.
6. Enable sharing using the toggle switch in the Enable sharing section.
7. Select Authorization in the left menu, and under OAuth 2.0 (3LO), select Configure.
8. Copy the Authorization URL(s) and distribute to your users.

Note that:

• OAuth 2.0 (3LO) apps are installed on a per-user basis, so you'll have to send the link to all the users you want to grant access to.
• Enabling sharing doesn't make your app available on the Atlassian Marketplace. Although OAuth 2.0 (3LO) apps can be listed on the Atlassian Marketplace, they will appear as informational listings only, with limited Marketplace features.

Known issues

We are aware of the following issues with OAuth 2.0 (3LO). Some of the issues have workarounds, which are described below. Others do not have workarounds, but are listed so that you are aware of them. If you discover an issue that is not listed below, raise a ticket at https://ecosystem.atlassian.net/projects/ACJIRA.

• Implicit grant flow not supported
• Site-scoped grants limitations
• Apps cannot declare searchable entity properties

Implicit grant flow not supported

OAuth 2.0 (3LO) currently supports the code grant flow only. It does not support the implicit grant flow. We understand that this is preventing people from using OAuth 2.0 (3LO) for standalone mobile apps and web/JavaScript (Chrome, Electron) apps and we are investigating ways to address this.

Site-scoped grants limitations

The current implementation of OAuth 2.0 (3LO) uses site-scoped grants, which means that the user only grants access to a single site each time they complete the consent flow. Be aware that there are a few limitations to this:

• If your integration needs information from multiple sites at one time, then the user will be required to go through multiple consent flows (one for each site).
• The consent screen currently requires the user to select the site that they want to grant access to. This can be confusing for users if there are multiple sites.
• With site-scoped grants, an access token can have access to multiple sites. This means that an app can't delete an access token to revoke access. For example, an access token could grant access to site A, then delete it to remove access. However, if the user grants the app access to site C later, the app will be issued with an access token with access to sites A and B. The only way access can be removed is for the user to revoke access via the Connect apps tab in their account settings at https://{subdomain}.atlassian.net/people/{account_id}/settings/apps.

(Jira only) Apps cannot declare searchable entity properties

Jira apps can store and read the values of entity properties (issue properties and project properties) using the REST API. However, in the current implementation of OAuth 2.0 (3LO), Jira apps cannot declare searchable entity properties. This means that if your app uses OAuth 2.0 (3LO), it won't be able to refer to entity properties in JQL queries.

Frequently asked questions

• How do I get a new access token, if my access token expires or is revoked?
• 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?
• How do I configure the refresh token behavior?
• What happens when I migrate from the persistent refresh token to rotating refresh token?
• How do I migrate from the persistent refresh token to rotating refresh token?

How do I get a new access token, if my access token expires or is revoked?

You have two options:

• Initiate the entire authorization flow from the beginning again.
• Use a refresh token to get another access token and refresh token pair.

Use a refresh token to get another access token and refresh token pair

Refresh tokens are implemented using rotating refresh tokens.

Rotating refresh tokens issue a new, limited life refresh token each time they are used. This mechanism improves on single persistent refresh tokens by reducing the period in which a refresh token can be compromised and used to obtain a valid access token.

To get a refresh token in your initial authorization flow, add offline_access to the scope parameter of the authorization URL. Once you have the refresh token, exchange it for an access token by calling the token URL. Each refresh token is valid for 30 days.

Use the following values to construct the request body:

• grant_type: Set to refresh_token.
• client_id: (required) Set this to the Client ID for your app. Find this in Settings for your app in the developer console.
• client_secret: (required) Set this to the Secret for your app. Find this in Settings for your app in the developer console.
• refresh_token: The refresh token that you obtained with your original access token.

1
2
3
4

curl --request POST \
  --url 'https://auth.atlassian.com/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "refresh_token", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "refresh_token": "YOUR_REFRESH_TOKEN" }'

If successful, a new access token is returned that you use to make calls to the product API. With rotating refresh tokens enabled, you receive a new refresh token as well and the refresh token you used for the request is disabled. If you are using persistent refresh token you receive a new access token and your original refresh token remains valid.

This is an example response with a refresh token:

1
2
3
4
5
6
7
8
9

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <string>,
  "refresh_token": <string>,
  "expires_in": <expiry time of access_token in second>,
  "scope": <string>
}

Otherwise, if an error is returned, see the list below for possible causes:

• 403 Forbidden with {"error": "invalid_grant", "error_description": "Unknown or invalid refresh token.": This error is returned when:
  • The user's Atlassian account password has been changed. Change the password back to the original password or initiate the entire authorization flow from the beginning again.
  • Your app is using rotating refresh tokens, but the app is not replacing the existing refresh token with the new refresh token returned.

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
3
4

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

Example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
  "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.

How do I configure the refresh token behavior?

Each time they are used, rotating refresh tokens issue a new limited life refresh token that is valid for 30 days. This mechanism improves on single persistent refresh tokens by reducing the period in which a refresh token can be compromised and used to obtain a valid access token.

If your refresh token expires, your user will need to complete the entire authorization flow from the beginning again.

You can enable rotating refresh tokens from the developer console, like this:

1. Select your integration in the developer console.
2. Select Authorization.
3. Select Use rotating refresh tokens from the refresh token options.
4. Save your changes.

What happens when I migrate from the persistent refresh token to rotating refresh token?

• For the first access token request after migration, your persistent refresh token is used to get a new access token and a refresh token. But, once you get a new refresh token all the previous refresh tokens are disabled.
• You will get a new refresh token and an access token pair with every access token request.
• Migrating to rotating refresh token from persistent refresh tokens doesn't force your user to consent to the app again.

How do I migrate from the persistent refresh token to rotating refresh token?

To migrate from persistent refresh token to rotating refresh token:

• Enable rotating refresh token in your app by following How do I configure the refresh token behavior?.
• Every new refresh token returned invalidates the refresh token used to get the new access token. Update your code to replace the existing refresh token with the new refresh token. See Use a refresh token to get another access token and refresh token pair for more details.

This TypeScript example shows one way to update the refresh token:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

  const response = await fetch(`https://auth.atlassian.com/oauth/token`, {
      method: 'POST',
      headers: {
        'content-type': 'application/json'
      },
      body: JSON.stringify({
        grant_type: 'refresh_token',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        refresh_token: this.refreshToken
      })
    });
    
    const json = response.json();
    
    this.accessToken = json.access_token;
    
    if(json.refresh_token) { 
      this.refreshToken = json.refresh_token;
    }