​
Overview

Pre-built tooling

Pre-built integrations

Access requirements

Setup guide

Useful links

API gotchas

​
Pre-built tooling

​
Pre-built integrations

Not seeing the integration you need? Build your own independently.

​
Access requirements

Pre-RequisitesStatusComment
Paid dev account✅ Not requiredFree, self-signup for an Atlassian developer account.
Paid test account✅ Not requiredFree Jira Cloud instance can be used for testing.
Partnership✅ Not required
App review⚠️ ConditionalRequired only if you want to list your app on the Atlassian Marketplace.
Security audit✅ Not required

​
Setup guide

1

Create an Atlassian developer account

If you don’t already have one, sign up for an Atlassian developer account.

2

Create a new OAuth 2.0 (3LO) app

  1. Go to the Atlassian Developer Console.
  2. Click Create and select OAuth 2.0 integration.
  3. Enter a name, agree to Atlassian’s developer terms by checking the agreement checkbox for your app and click Create.
  4. Your app will be created and you’ll be taken to the app management page.
3

Configure OAuth 2.0 (3LO)

  1. In the left sidebar, select Authorization.
  2. Next to OAuth 2.0 (3LO), click Add.
  3. Enter https://api.nango.dev/oauth/callback as the Callback URL.
  4. Click Save to save your changes.
4

Add API permissions

  1. In the left sidebar, select Permissions.
  2. Find the Jira API and click Add, and then click Configure.
  3. Click Edit Scopes then select the scopes your application requires. Common scopes include:
    • read:jira-user - Read user information
    • read:jira-work - Read issues, projects, and workflows
    • write:jira-work - Create and update issues
    • delete:jira-work - Delete issues
    • manage:jira-project - Manage project settings
    • manage:jira-configuration - Manage Jira instance settings
    • offline_access - Get refresh tokens (required for long-term access)
  4. Click Save to save your changes.
5

Obtain your client credentials

  1. In the left sidebar, select Settings.
  2. Note your Client ID.
  3. Copy both the Client ID and Secret by clicking the copy buttons next to them, as you’ll need them when configuring your integration in Nango.
6

Make your app available to users (optional)

If you want to distribute your app to other users:

  1. In the left sidebar, select Distribution.
  2. In Distribution controls, click the Edit button, then select the Sharing radio button.
  3. Return to the Authorization page and copy the Authorization URL to share with your users.

Note: By default, your app is private and can only be used by you. Making it public allows other users to authorize your app.

7

Next

Follow the Quickstart.

Need help getting started? Get help in the community.
TopicLinks
GeneralAtlassian Developer Portal
Atlassian Developer Console
Jira Cloud Platform Documentation
DeveloperOAuth 2.0 (3LO) Apps Documentation
OAuth Scopes Reference
Jira REST API v3 Documentation
API Rate Limits
Basic Auth Documentation
Distributing OAuth 2.0 Apps
Atlassian Marketplace
Contribute useful links by editing this page

​
Common Scopes

ScopeDescription
read:jira-userRead user information
read:jira-workRead Jira work items (issues, projects, etc.)
write:jira-workCreate and update Jira work items
offline_accessAccess to refresh tokens for offline access

​
API gotchas

  • Refreshing tokens require the offline_access scope when creating the integration on the Nango UI.
  • You will need to fetch your Cloud ID to be able to make API requests to the Jira API v3. You can do this with the proxy by calling:
const response = await nango.get({
    endpoint: `oauth/token/accessible-resources`,
    baseUrlOverride: 'https://api.atlassian.com'
});
const cloudId = response.data[0].id;

You can then construct your URL as follows: https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/<endpoint>

  • When you create an OAuth 2.0 (3LO) app, it’s private by default. Before using the integration, you must make your app public. If you want to make your app public, find the how-to here.
  • Refresh tokens will expire after 365 days of non use and will expire by 90 days if the resource owner is inactive for 90 days. Make sure you call nango.getConnection() at least every 365 days to trigger a refresh. See reference here.
  • Nango also supports BASIC auth for REST APIs in Jira. To use this feature, provide your email as the username and your api_token as the password. To generate an api_token, please refer to the Manage Atlassian API Tokens section
  • You will also need to supply your subdomain. When logged into your Atlassian account or Jira instance, look at the URL in your web browser. The subdomain part before .atlassian.net is your Jira subdomain.
  • The state parameter is required for security in the OAuth flow to prevent CSRF attacks. Nango handles this automatically.
  • Jira’s OAuth implementation uses rotating refresh tokens. Each time you refresh an access token, you’ll receive a new refresh token that invalidates the previous one.
  • When making API calls, remember that the permissions of the user who authorized your app will limit what your app can do, regardless of the scopes you’ve requested.
  • The Jira REST API has different versions (v2 and v3). Make sure you’re using the correct version for your needs.
Contribute API gotchas by editing this page

Connect to jira-basic

Guide to connect to jira-basic using Nango Connect.

Suggest editsRaise issue