Jira integration guidelines

When you integrate Jira into your product, your users can create tickets and view issues in the same place they do their work. No context-switching to add or track work.

General guidelines and requirements

To ensure our mutual customers have the best experience, we encourage you to build Jira integrations considering all guidelines outlined on this page. Some may be used independently of each other, but they're designed to work together for a great end-to-end experience with the Jira APIs available today.

These guidelines apply to the Jira family of products (Jira Software, Jira Work Management, Jira Service Management). We expect to evolve and expand this page as we strive to support deeper integrations.

✅ Experiences must be a logical and familiar extension of Jira

Our customers trust their data to look and function as expected, no matter what platform they’re on. Jira should feel intuitive while still demonstrating the overall value of our product when embedded in your product.

✅ Jira must remain the single source of truth

Your product UI is one way that users interact with their Jira data, but it should be consistent no matter what interface they use. Any changes that users make to issues in your product should be automatically saved back to Jira, to maintain data integrity.

✅ Solutions must be built for all Jira customers (don’t break Jira)

Jira must work for all customers, regardless of their configurations. In general, if a change that you make to your product breaks the experience for any Jira customers, don’t do it.

✅ Read the Terms before contacting Atlassian

Before contacting us for additional display or trademark permissions, read through our Cloud Terms of Service and Developer Terms. If you can’t find the answer to your question, you can contact us at trademarks@atlassian.com.

❌ Don’t recreate Jira boards, backlogs, or workflows

Instead of recreating, link directly to the Jira feature. There are many powerful configuration options available to Jira users, and many customers have taken full advantage of them to create custom configurations to fit their processes. To ensure that all instances render the way they’re intended to, regardless of custom setups, elements like boards, backlogs, and workflows should only be presented in their full, genuine state – in Jira itself.

Jira branding

Users should know that they’re using Jira in your product.

Issue management

If your integration supports multiple issue views or issue management, Jira must be clearly attributed in one of the following ways:

✅ Use the word “Jira” on the feature’s title page:

✅ Display a text link or the “Powered by Jira” asset provided by Atlassian. The text link or the “Powered by Jira” asset must be placed above the fold on your page, with a link to Jira. Here are the images for you to download and use:

Linking to Jira

Before a user clicks a link or button in your product, they must know that they're taking action in, or navigating to, Jira.

✅ You must label the button or link to create a new issue as “Create Jira issue”.

✅ You must include “Jira” in link text to source projects, issues, or other views. For example, “Open in Jira”.

Displaying Jira issues

An issue represents a single unit of work and is the smallest Jira object to incorporate into your product. Issues should be presented in a way that gives context to a user’s work, allows them to reference specific issues, and makes their task as clear as possible. This gives users an evolving and updating record of work as it progresses across tools.

A single Jira issue

Every Jira issue has a value for the Issue type, Issue key, Summary, and Status fields. Other fields, such as Assignee, Priority, and Labels, are optional, and depend on how administrators configure their instances:

✅ Whether you choose to display a Jira issue as a link, a card, or in a table row, you must always show the issue key:

When building an integration across two systems, you likely have two separate user management systems with different user data. If you choose to display user data, like avatars and/or names for the assignee, reporter, etc., make sure the data comes from Jira.

✅ You must display Jira user information with Jira issues.

Multiple Jira issues

When representing multiple issues, you’ll need to represent the issue key along with additional data so users can easily identify issues and understand its content at a high level.

✅ You must display the issue type icon, issue key, summary, and status in data tables. When linking to an issue in a data table, we recommend you use the issue key (as shown in the image below) or the entire row as a navigation link to the issue details:

Issue details

Representing complete issue content can be challenging due to customizations, complex rules, and rich content, which aren’t supported in our public APIs.

This experience is best delivered by Jira. Users should always have a clear and easy path to the original issue.

✅ You must always provide a link to the original Jira issue details:

Multiple issue providers

If you support integrations with multiple issue providers, make sure Jira issues remain separated at the project level. Users need to clearly identify a Jira issue before they click it. This can be accomplished through the page or feature-level attribution. Issue level attribution is very difficult when issues from different providers are co-mingled in one aggregated worklist. You can include Jira issues in aggregated search results or dashboards.

✅ You must separate Jira issues from other issue providers at the project level.

Editing Jira issues

Issues may have fields that aren't supported through the Jira API, so if you want to allow users to edit Jira issues, link directly to the issue in Jira. This includes taking actions like updating the issue’s status, adding attachments, modifying the description, or adding rich content.

✅ You must open the issue detail view in Jira. We recommend the link opens a new browser tab.

Creating Jira issues

If you want to let users create issues from your product, make sure the button or link for this task is properly attributed to Jira.

✅ You must label the button or link to create a new issue as “Create Jira issue”:

✅ You must use the “Create issue” experience provided by Jira.

If you want to allow users to create issues from your product, you must open the "Create issue" experience provided by Jira. This opens a standalone page that handles the logic and workflow of the source Jira application:

This is because, depending on how administrators have configured their instances, issues may have required fields that use rich styles beyond standard HTML inputs that can’t be surfaced through the Jira API.

We recommend that this opens the "Create issue" experience in a new browser tab.

Feedback

We’re keen to hear your thoughts about this page. You can leave anonymous feedback through the star rating in the top-right corner of this page.

Next steps

• View what’s possible with the Jira Cloud platform REST API

• View what’s possible with the Jira Software Cloud REST API

• Get familiar with the Atlassian Design guidelines

• Get familiar with the Atlassian Cloud Terms of Service Cloud Terms of Service