Jira

Access the Jira API in 2 minutes 💨

🚀 Quickstart

1. Create an integration

   In Nango (free signup), go to Integrations -> Configure New Integration -> Jira.

2. Authorize Jira

   Go to Connections -> Add Test Connection -> Authorize, then log in to Jira. Later, you’ll let your users do the same directly from your app.

3. Call the Jira API

   Let’s make your first request to the Jira API (fetch a list of issues). Replace the placeholders below with your secret key, integration ID, and connection ID:

   cURL

   curl "https://api.nango.dev/proxy/ex/jira/{connectionConfig.cloudId}/rest/api/3/search?maxResults=10" \
     -H "Authorization: Bearer <NANGO-SECRET-KEY>" \
     -H "Provider-Config-Key: <INTEGRATION-ID>" \
     -H "Connection-Id: <CONNECTION-ID>"
   

   Node

   Install Nango’s backend SDK with npm i @nangohq/node. Then run:

   import { Nango } from '@nangohq/node';
   
   const nango = new Nango({ secretKey: '<NANGO-SECRET-KEY>' });
   
   const res = await nango.get({
       endpoint: '/ex/jira/{connectionConfig.cloudId}/rest/api/3/search',
       params: {
         maxResults: 10
       },
       providerConfigKey: '<INTEGRATION-ID>',
       connectionId: '<CONNECTION-ID>'
   });
   
   console.log(JSON.stringify(res.data, null, 2));
   

   Or fetch credentials dynamically via the Node SDK or API.

   The {connectionConfig.cloudId} in the URL represents the cloudId. You can get this value from your connection configuration after creating the connection. The cloudId is automatically set by Nango.

✅ You’re connected! Check the Logs tab in Nango to inspect requests.

Next step: Embed the auth flow in your app to let your users connect their Jira accounts.

🧑‍💻 OAuth app setup

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 Changes 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. For reference, see our Common Scopes table below.
   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

   1. In the left sidebar, select Distribution.
   2. In Distribution controls, click the Edit button, select the Sharing radio button, enter a Privacy Policy URL and then click the Save changes button.
      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.

Common Scopes

Scope	Description
read:jira-user	Read user information
read:jira-work	Read Jira work items (issues, projects, etc.)
write:jira-work	Create and update Jira work items
delete:jira-work	Delete issues
manage:jira-project	Manage project settings
manage:jira-configuration	Manage Jira instance settings
offline_access	Access to refresh tokens for offline access

🔗 Useful links

Topic	Links
General	Atlassian Developer Portal
	Atlassian Developer Console
	Jira Cloud Platform Documentation
Developer	OAuth 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

🚨 API gotchas

• Refreshing tokens require the offline_access scope when creating the integration on the Nango UI.
• When connecting to Jira, you have two options for specifying which Jira site to connect to:
  1. Provide a Subdomain during connection creation (recommended)
  2. Let Nango auto-select the first available site (legacy behavior): If no Subdomain is specified, Nango will use the first site from the accessible resources api.

const response = await nango.get({
    endpoint: `oauth/token/accessible-resources`,
    baseUrlOverride: 'https://api.atlassian.com'
});
const cloudId = response.data[0].id;

• A single Jira OAuth token can be valid for multiple Atlassian sites. For example, the same token might grant access to both “nango-hq.atlassian.net” and “nango-test.atlassian.net”. This is why specifying the Subdomain during connection creation is important if you need to connect to a specific site.

• The connection process works as follows:

  1. Nango fetches all accessible sites for the OAuth token
  2. If you specified a Subdomain, Nango finds the matching site and sets its cloudId
  3. If no Subdomain is specified, Nango uses the first available site and sets its cloudId
  4. The selected site’s cloudId and subdomain are stored in the connection configuration

• The cloudId is required to make API requests to the Jira API v3. Nango handles getting this automatically by matching it to your specified subdomain if provided, or by selecting the first available site if it is not. You will then need to construct your Nango integration’s endpoint as follows: /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.

• 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

Questions? Join us in the Slack community.