Create a Jira App to enable OAuth for your Integration

What this tutorial will cover:

Building integrations with Jira? You’ll want to create a Jira app on their developer console and enable OAuth. This tutorial will get you on your way! We’ll cover how to:

1. Create/login to an Atlassian (Jira) developer account

2. Create an Atlassian app to get started building a Jira app

3. Interact with Atlassian’s authentication endpoints from your client app

4. Test Jira API endpoint to prove out authentication

5. Get your Jira integration more production-ready

But first, a quick plug: Paragon is an embedded integration platform used by engineering teams to build native integrations faster and more reliably in production. If you’re interested in learning more, there’s more information about Paragon at the end of the tutorial.

Create an Atlassian developer account (if you don't have one)

Atlassian covers a suite of products including Jira, Confluence, and Bitbucket. Creating an Atlassian developer account allows us to create apps that can interact with APIs for all of these products, including Jira.

You can log in to the Atlassian developer console with your normal Atlassian account at https://developer.atlassian.com/. If you don’t already have an Atlassian account, create an account with your work email.

Once logged in, you should have a “Developer console” option in your navbar under your account.

Create your Atlassian app to get started with development

When you’re in the Atlassian developer console, click on “Create” to create a new application. We’ll want to create an “OAuth 2.0 integration.” Forge is Atlassian’s serverless platform to build Atlassian-specific apps, but in most cases if you need to build integrations across different 3rd-party providers, we recommend the general OAuth integration.

Configuring Jira Scopes & Redirect URL

Next, click into your newly created app, and go to the “Permissions” tab. This is where you’ll select the scopes your development version Jira app will need. Configure the right scopes for the Jira API using their official documentation: https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/

Next, in the “Authorization” tab, input your callback URL, this is the URL that Atlassian will redirect your users to after they log in to Atlassian. Note the “Jira platform REST API authentication URL.” This is the URL your application should redirect users to, to bring users to the Atlassian login page. This URL needs to have your Atlassian application’s client ID and Jira API scopes.

Note: Make sure to include offline_access in your scopes if you’d like a refresh token

Get your access code and token with Atlassian’s auth endpoints

The last thing we’ll need from the Atlassian developer console is the client ID and client secret. Navigate to the “Settings” tab on the sidebar. “Authentication details” is where you can find your client ID and secret. We’ll need these fields in our application code.

To reiterate, Atlassian will use your callback URL to return the user back to your application after they’ve authenticated with their Atlassian account. In the callback URL, you’ll get back an access_code as a URL parameter.

Access codes are one time use and will allow you to retrieve an access token with a POST request to Atlassian’s auth service.

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"}'

The response will look something like this:

{
  "access_token": "asdfjkl;",
  "expires_in": 3600,
  "scope": "read:jira-user"

Test token with a Jira API endpoint

If you’ve followed along up to this point, you should have a valid access token! Use this token in the request headers when sending API requests to the Jira API.

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

If your access token is expired, use your refresh token to request a fresh access token.

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" }'

For the full documentation on refresh policies, check them out here: https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#faq1

Make your Jira integration more production ready

That’s it! You should now have a Jira integration, allowing your application to call the Jira API with your users’ credentials. As you get ready to ship your new integration, it will be important to think about:

• Jira OAuth refresh token mechanisms

• Jira's API rate limits

• pagination when handling large response sizes

• handling credentials across multiple tenants

Paragon takes care of these challenges out-of-the-box and simplifies the OAuth process if you’d like to skip all of the above steps to get directly to working with the Jira API.

Just input your Atlassian client ID, secret, and scopes in Paragon’s Jira settings page, use our provided redirect URL, and you’re good to go!

To initiate the OAuth flow in your application, embed our pre-built Connect Portal UI directly in your frontend with just a few lines of code for a completely white-labeled experience.

If you’re interested in learning more about Paragon and how it fits with your product, check out this article on how Paragon fits into your tech stack, our docs, or sign up for a free trial.