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. In the Authorization code flow, the app redirects the user to a specific URL owned by Atlassian. We then display a "consent screen" where the user can agree to allow the app to have the scopes specified in the URL. Once consent has been given by the user, Atlassian will redirect the user back to the app to the specified redirect uri with a query parameter that has a authorization code. The app can then exchange this code with the OAuth endpoint to receive an access token that can be used in API.

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
https://auth.atlassian.com/authorize?
  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:

• 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.

Exchange authorization code for access token

1
2
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
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 in Making Calls to API