Integrating with self-hosted tools using OAuth

Note that:

  • The info on this page is only for integrating Jira Software Cloud with on-premise/server tools. If you‘re using a cloud-based tool for your CI/CD pipeline, see this page instead or check the Atlassian Marketplace.
  • This feature is currently in Beta. We're still iterating and making improvements on it.

OAuth credentials allow you to integrate your Jira Software Cloud site with self-hosted development and build tools like Bitbucket Server and Jenkins. This means you won’t need to open your firewall or install a third-party add-on to associate development or release information with Jira issues.

This is a system-to-system integration, and isn’t associated with any Jira user. This means it will continue to work regardless of any changes to your user-base.

In the future, this mechanism will support more data types, such as development information from Bitbucket Server or GitHub Enterprise.

Before you begin

You must be a site admin for Jira Cloud, as well as an admin for the tool you wish to integrate with.

Create OAuth credentials in Jira Cloud

To create OAuth credentials:

  1. Select  > Apps.

  2. From the sidebar, select OAuth credentials.

  3. Select Create credentials.

  4. Enter the following details:

    • App name - The name of the tool. This will display in your list of credentials.

    • Server base URL -  A URL to the tool you're integrating with, used for future actions from the Jira issue view. 

    • Logo URL - A URL to the tool’s logo, which will be used as an icon in the list of credentials.

    • Permissions - The permissions that the app has to call the DevOps related APIs.

  5. Select Create.

Your OAuth credentials will include a client ID and client secret.


Each OAuth Credential (2LO) that you create is tied to a specific set of scopes, or what APIs you'll be allowed to use when sending requests to Jira.

Because this feature is in Beta, the scopes are extremely limited at this time. You can only use the OAuth Credentials (2LO) to send data about build and deployment information and associate that to Jira issues using the Builds API and Deployments API.

Future scopes:

  • Feature Flag API - To send feature flag data and associate that with Jira issues.

How it works

After OAuth credentials are created in Jira, they must be copied to the tool you wish to integrate with.

At a high level, this is how it works:

  1. You create OAuth credentials in Jira for your tool.
  2. You copy these credentials to the tool you want to integrate with.
  3. The credentials must be referenced in a plugin or script, which triggers Jira-related data to be sent back to Jira.

By using OAuth, you get the following benefits:

  • Your Jira instance is secure, because the tool you integrate with doesn't have complete control over your Jira Cloud instance.
  • Your Jira data is secure, because the tool you integrate with doesn't have any read access to Jira Cloud. The only data that is exchanged is the issue-related information that is sent from the other tool to Jira.
Last modified on Nov 17, 2021

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.