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)

Consult the Jira Service Management Enabling OAuth 2.0 (3LO) documentation.

Implementing OAuth 2.0 (3LO)

Consult the Jira Service Management Enabling OAuth 2.0 (3LO) documentation. Only constructing request URL is different than Jira Service Management.

Construct your request URL using the following structure:

https://api.atlassian.com/ex/jira/{cloudid}/jsm/ops/api/{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:
• /v1/alerts for the alert endpoint in the Jira Service Management operations REST API.
• /v1/schedules for the schedules endpoint in the Jira Service Management 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/jsm/ops/api/schedules

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://api.atlassian.com/jsm/ops/api/{cloudId}/{api} rather than the request URLs shown above.