Jira

​

Overview

​

Pre-built tooling

​

Pre-built integrations

​

Access requirements

​

Setup guide

​

Useful links

​

Common Scopes

​

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 baseUrl during connection creation (recommended)
  2. Let Nango auto-select the first available site (legacy behavior): If no baseUrl 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 baseUrl 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 domain, Nango finds the matching site and sets its cloudId
  3. If no domain is specified, Nango uses the first available site
  4. The selected site’s cloudId and domain are stored in the connection configuration

• The cloudId is required for making API requests to the Jira API v3. Nango handles this automatically by matching it to your specified baseUrl or selecting the first available site. Your API URLs will be constructed as: https://api.atlassian.com/ex/jira/${cloudId}/rest/api/3/<endpoint>

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
• 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.