The Jira Cloud platform REST API

Before you begin

To complete this tutorial, you need:

Forge apps

For Forge apps, REST API scopes
are used when authenticating with Jira Cloud platform. See Add scopes to call an Atlassian REST API for more details.

The URIs for Forge app REST API calls have this structure:

/rest/api/3/<resource-name>

For example, /rest/api/3/issue/DEMO-1

Other integrations

For integrations that are not Forge or Connect apps, use OAuth 2.0 authorization code grants (3LO) for security
(3LO scopes are shown as for operations OAuth scopes required). See
OAuth 2.0 (3LO) apps
for details.

The URIs for OAuth 2.0 (3LO) app REST API calls have this structure:

Process

The authentication process, commonly known as the “OAuth dance,” works by the resource owner granting
access to their information on the resource by authenticating a request token. The consumer uses the
request token to obtain an access token from the resource.

This diagram shows the process in more detail:

Roles

The roles in the OAuth authentication process, and how they relate to authenticating with Jira, are:

See it in action

This walkthrough shows how the OAuth authentication process works. First, it configures Jira so that
the example client can authenticate against it using OAuth. Then it uses the example client to initiate
the “OAuth dance” before making an authenticated request to the Jira REST API.

Step 1: download the example app

1. Clone the example Oauth client application code from the atlassian-oauth-examples/ repository
2. Navigate to the java directory:

3. Build the client by running this command in the root of the project:

4. Navigate to the target directory in the project and run:

   Ignore the exception in the output. This step generates the config.properties file, which is used later.

Step 2. configure the client application as an oauth consumer

In Jira, OAuth consumers are represented by application links. Application links use OAuth with
RSA-SHA1 signing for authentication. This means that a private key is used to sign requests rather
than the OAuth token secret/consumer secret. The following steps generate an RSA public/private key
pair and creates a new application link in Jira that uses the key.

Generate an RSA public/private key pair:

1. In a terminal, run these openssl commands. Do this
   anywhere in your file system:

   This generates a 1024 bit private key, creates an X509 certificate, and extracts the private key
   (PKCS8 format) to the jira_privatekey.pcks8 file. It then extracts the public key from the
   certificate to the jira_publickey.pem file.

2. Copy the private key from the jira_privatekey.pcks8 file.

3. Navigate to the target directory in the example OAuth client project. Edit the config.properties
   file and make these changes:

4. Save the config.properties file.

Configure the client app as a consumer in Jira, using application links:

Step 3. do the oauth dance

The “OAuth dance” is a term used to describe the process of getting an access token from the
resource that the consumer can use to access information on the resource. This involves a “dance” where
different tokens are passed between the consumer, resource owner, and resource (see OAuth overview above).