Rate this page:
This page shows you how to configure OAuth 2.0 (3LO) (also known as "three-legged OAuth" or "authorization code grants") apps. Note, you cannot use OAuth 2.0 (3LO) with Forge or Connect apps. OAuth 2.0 (3LO) is used to allow external applications and services to access Atlassian product APIs on a user's behalf.
OAuth 2.0 (3LO) involves three parties:
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:
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).
Before you can implement OAuth 2.0 (3LO) for your app, you need to enable it for your app using the developer console.
Note, if you haven't already added an API to your app, you should do this now:
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:
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: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.
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:
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.
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 will return an access token. This access token can be used to make API calls, as described below.
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:
cloudid
for your site. cloudid
.cloudid
for your siteMake 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:
1 2 3 4 5 6 7 8 9 10 11 12
[
{
"id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
"name": "your-domain1",
"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"
}
]
1 2 3 4 5 6 7 8 9 10 11 12
[
{
"id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
"name": "your-domain1",
"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"
}
]
1 2 3 4 5 6 7 8 9 10 11 12
[
{
"id": "1324a887-45db-1bf4-1e99-ef0ff456d421",
"name": "your-domain1",
"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"
}
]
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:
https://api.atlassian.com/ex/jira/{cloudid}/{api}
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 Desk 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.
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'
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:
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 /oauth/token/accessible-resources
Request parameters: None
Example:
1 2
curl --header 'Authorization: Bearer <access_token>' \
--url 'https://api.atlassian.com/oauth/token/accessible-resources'
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
[
{
"id": "8594f221-9797-5f78-1fa4-485e198d7cd0",
"name": "your-domain2",
"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": "your-domain1",
"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.
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:
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:
You can search for an app using the search bar above the app table.
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:
Select Settings in the left menu to view your app's authentication details, or to change your app’s name, description, or avatar.
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.
You can only delete an app if it's not installed anywhere.
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 people, you must make it public.
Your app is now public and can be used by others.
Note that making your app public does not make it available on the Atlassian Marketplace. Listing an OAuth 2.0 (3LO) app on the Atlassian Marketplace is currently not supported.
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.
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.
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:
https://{subdomain}.atlassian.net/people/{account_id}/settings/apps
.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.
You have two options:
A refresh token can be returned with the access token in your initial authorization flow. To do this,
add the offline_access
scope 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:
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" }'
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.If successful, a new access token will be returned that you can use to make calls to the product API. 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.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.
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:
state
parameter.client_id
.code
parameter.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:
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:
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"
}
}
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.
Rate this page: