Jira Authentication Methods

OneConnect supports multiple authentication methods for connecting to Jira Cloud. 

Before configuring the integration, review the available options and select the method that best aligns with your organization's security requirements and governance standards.

Important: The user configuring the integration must have the appropriate administrative permissions in Jira and Atlassian to authorize access. 

Supported Authentication Options

OneConnect supports the following Jira authentication methods:

• Jira API Token (without scopes)
• OAuth 2.0 (3LO) with API Token and Scopes (Recommended)

Each option is outlined below, including setup requirements, advantages, and limitations.

Jira API Token (Without Scopes)

This method uses a Jira user account's email address and an API token generated from Atlassian, and the Jira environment URL. The token inherits all permissions of the user account.  

Recommendation: Use a dedicated Jira service account rather than a personal user account. 

Pros:

• Very easy to set up - Generate a token and configure the connector. 
• Stable and predictable - Minimal configuration and no app registration.
• Service-account friendly - Commonly used with dedicated integration users. 

Cons:

• No granular permissions - Token has the same access as the user account
• Weaker security posture - Long-lived token stored at rest. 
• Limited governance - harder to audit or restrict integration access. 
• Increasingly discouraged - Atlassian does not recommend using this in the future.

Generate a Jira API Token (Without Scopes)

The user generating the token must have read, write, and manage access in Jira. 

1. Log in to your Jira environment.
2. Navigate to: https://id.atlassian.com/manage-profile/security/api-tokens. 
3. Click Create API token.
4. Provide a name and expiration date.
   1. Expiration dates can only go up to 1 (one) year from the creation date. If expired, a new token must be created and replaced within your integration. 

5. Click Create.

6. Copy the token and store it securely.

7. Use this token when configuring the Jira connector in OneConnect.

OAuth 2.0 (3LO) with API Token and Scopes (Recommended)

OAuth 2.0 (3LO) provides a modern, secure authentication flow with granular permission control and improved governance. This option requires creating an OAuth app in Atlassian and authorizing it from OneConnect.

Required Information:

• Jira environment URL

• Jira API token with scopes

• Jira App Client ID

• Jira App Client Secret

• Jira Cloud ID

• Authorization approval from a Jira Administrator

Pros:

• Granular scopes – Access limited to exactly what the integration needs

• Stronger security – Short-lived access tokens with refresh support

• Enterprise-ready – Preferred by security teams and auditors

• Visibility & control – Access can be reviewed and revoked in Atlassian

Cons:

• More complex setup – Requires app creation and consent flow

• Ongoing maintenance – Scopes may need updates over time

• User-context based – Access depends on the authorizing user remaining active

Please review this article for the list of scopes.

Create & Configure the OAuth App (Atlassian)

The user must have access to the Atlassian Developer Console (typically an Atlassian Organization Admin or delegated app administrator). 

Create the OAuth App

1. Navigate to the Atlassian Developer Console: https://developer.atlassian.com/console. 

2. Click Create → OAuth 2.0 Integration.

3. Enter a unique name for the integration.

4. Review and accept the Atlassian Developer Terms.

5. Click Create.

You will be redirected to the app’s Overview page.

Configure Permissions

From the app’s Overview page, select Permissions from the left navigation.

Jira API – Classic Scopes

Under Jira Platform REST API, click Edit Scopes and enable:

• read:jira-work 

• manage:jira-project 

• manage:jira-configuration 

• read:jira-user 

• write:jira-work 

• manage:jira-webhook 

• manage:jira-data-provider 

Click Save. 

Jira Service Management API – Classic Scopes

Enable the following scopes:

• read:servicedesk-request 
• manage:servicedesk-customer 
• write:servicedesk-request 
• read:servicemanagement-insight-objects 

Click Save. 

Jira API – Granular Scopes

Click Edit Scopes and add the following:

• View Issues – read:issue:Jira 
• View Projects – read:project:Jira 
• View Boards, Backlogs, and Related Items – read: board-scope:jira-software 
• View Sprints – read:sprint:jira-software 
• View Issue Details - read:issue-details:jira 
• View Avatars – read:avatar:jira 
• View application roles – read:application-role:jira
• View groups – read:group:jira 
• View users – read:user:jira 
• View user properties – read:user.property:jira 
• Create and update projects – write:project:jira 

Click Save. 

Note: A total of 22 Jira API permission scopes should be configured. 

The permissions outlined in this guide represent the maximum set required to unlock the full range of integration features, including the ability to sync data back (write-back).
 

Not every organization will need every feature. If you plan to use a subset of the available capabilities, you can safely reduce or turn off permissions that correspond to features you do not intend to use.

How to Decide Which Permissions You Need

Read-only sync: If you only need to pull data into OnePlan without writing changes back, you can limit permissions to read-only access.

Full bi-directional sync: If you want to sync data in both directions — including pushing updates, status changes, or new items — you will need the full set of permissions listed in this guide.

Tip: Start by identifying which integration features your team needs, then grant only the permissions required to support those features. You can always expand permissions later as your usage grows.

Set the Callback URL

1. Navigate to Authorization in the left navigation.

2. Click Add next to OAuth 2.0 (3LO).

3. Enter the callback URL:

   1. In the non EU region: https://my.oneconnect.ai/oauth/jira/callback

   2. In the EU region: https://eu.oneconnect.ai/oauth/jira/callback

4. Save your changes. 

Locate Client ID and Client Secret

1. Navigate to Settings in the left navigation.

2. Copy the Client ID and Client Secret.

3. These values are required when configuring the Jira connector in OneConnect.

Locate your Jira Cloud ID

1. Navigate to https://admin.atlassian.com

2. elect Apps → Atlassian Apps.

3. Choose Jira and click Manage App.

4. The Jira Cloud ID appears in the browser URL: admin.atlassian.com/o/{OrganizationId}/atlassian-apps/jira-software/{CloudId}

Create a Jira API Token with Scopes

1. Navigate to: https://id.atlassian.com/manage-profile/security/api-tokens. 
2. Click Create API token with scopes. 
3. Enter a unique name and set an expiration date (up to 1 year). 

4. Select Jira as the app.

5. Set Scope Type to Classic.

6. Select all available scopes (two pages, 12 scopes total).

7. Review and click Create Token.

8. Save the token securely for use in OneConnect.

Authorize the Integration in OneConnect

Before clicking Authorize in OneConnect:

• The OAuth app must be created in Atlassian
• Client ID, Client Secret, Jira API Token, and Cloud ID must be entered. 

A Jira Administrator must click Authorize in the Jira Connector (Advanced Options).

This will:

1. Prompt the user to select the Jira environment (if multiple exist)
2. Display a consent screen requesting approval
3. Require clicking Accept to complete the authorization. 

Uninstalling the OAuth App

Remove the App from Connected Apps

1. Navigate to: https://admin.atlassian.com/s/{CloudId}/user-connected-apps/tab/installed. 
2. Locate the integration app (the name given to your OAuth App).
3. Click View App Details > Uninstall. 
4. Confirm the uninstall. 

Delete the App from Atlassian Developer Console

1. Navigate to: https://developer.atlassian.com/console/myapps.
2. Select the app.
3. Open Settings.
4. Click Delete App and confirm. 

Warning: The app must be uninstalled first. Attempting to delete the app while still installed will fail with the message: "We couldn't delete this app, as it is currently installed somewhere."