> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-jira-integration.md).

# How to set up the Jira integration

An Admin connects Jira once at the account level. After that, anyone in your workspace can search Jira and link issues to planning cards on any journey map.

{% hint style="info" icon="clipboard-list" %}

#### In this guide

1. [Set up the Jira integration](#set-up-the-jira-integration)
2. [Verify the setup](#verify-the-setup)
3. [Use Jira in planning cards](#use-jira-in-planning-cards)
4. [Troubleshooting](#troubleshooting)
   {% endhint %}

#### Set up the Jira integration

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* Admin role at the account level. Only Admins can configure integrations, and the connection applies to the whole account.
* A Jira Cloud account with permission to create an API token.
  {% endhint %}

Jira uses a single authentication method: a personal Atlassian API token, plus your Jira site URL and the account email the token belongs to. This works with Jira Cloud only.

Here's a quick look at the full setup before you start.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2For99xDEElfps9uMDY60K%2Fuploads%2FmaxGXiG2wVWx31bOou4v%2Fsetup-jira-api-key.mp4?alt=media&token=ab5f2cd0-751e-4d7b-bc7a-cfe2c23feccc>" %}

{% stepper %}
{% step %}
**Open the Jira integration in Smaply**

Go to **Account Settings > Integrations** and click **Set up** next to **Jira**. The **Configure Jira** page opens with empty fields for your base URL, account email, and API token.

<figure><img src="/files/K4Ck8GhWWnk1a8JBpmlP" alt="The Configure Jira page in Smaply. A Jira API Configuration form shows three empty required fields labelled Jira Base URL, Jira Account Email, and JIRA API TOKEN, with a blue help block above listing three setup steps and a Save Configuration button below."><figcaption><p>Configure Jira, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Create an API token in Atlassian**

In a new tab, go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and sign in. Click **Create API token**, enter a **Label** so you can recognise it later, and set an expiry date. Click **Create**.

Note your Jira site URL (the address in the form `https://your-domain.atlassian.net`) and the account email the token belongs to. You need all three to connect.

{% hint style="warning" %}

#### **Important: copy the token before you close the dialog**

Atlassian shows the token only once. Click **Copy** and paste it straight into Smaply. If you lose it, create a new token and start this step again.
{% endhint %}
{% endstep %}

{% step %}
**Enter your details and save**

Back on the **Configure Jira** page, paste your site URL into **Jira Base URL**, your account email into **Jira Account Email**, and the token into the **JIRA API TOKEN** field. Click **Save Configuration**.
{% endstep %}

{% step %}
**Confirm the connection**

Smaply tests the connection and, once it succeeds, the page shows your saved details with a green confirmation. Jira is now available to everyone in your account.
{% endstep %}
{% endstepper %}

***

#### Verify the setup

Reopen the **Configure Jira** page from **Account Settings > Integrations**. A connected integration shows your base URL, account email, and a masked API token, with a green **Connection setup** message reading "Successfully connected to Jira as ...".

<figure><img src="/files/Jq54l8iEHalXgxg7cTxd" alt="The Configure Jira page in Smaply showing a connected integration. The saved Base URL, Email, and masked API Token are listed, with a green Connection setup callout confirming the account is connected to Jira, and Edit Configuration and Delete Configuration actions below."><figcaption><p>Connection established</p></figcaption></figure>

If you don't see the green confirmation, check the [Troubleshooting](#troubleshooting) section below.

***

#### Use Jira in planning cards

Once Jira is connected, anyone in your workspace can add a planning card to a journey map, search Jira, and link the issue it relates to. For the full flow, see [How to use planning cards](/journey-maps/cards/how-to-use-planning-cards.md).

***

#### Troubleshooting

The **Configure Jira** page shows the integration's current state. Pick the symptom below that matches what you're seeing.

<details>

<summary><strong>Connection Error or the connection won't save</strong> - Connection issue</summary>

The base URL, email, or token is wrong, or they don't belong together. Reopen **Configure Jira**, click **Edit Configuration**, and check each value:

* **Jira Base URL** is the full Cloud address in the form `https://your-domain.atlassian.net`, with no trailing path.
* **Jira Account Email** is the email of the Atlassian account the token was created under.
* The token is the most recent one you created, pasted with no extra spaces.

Save again. If it still fails, create a fresh token in Atlassian and re-enter all three values.

</details>

<details>

<summary><strong>No items found when adding a planning card</strong> - Search issue</summary>

The connection works but Jira returns nothing for your search. Check that the search text matches an issue you can open in Jira, and that the token's owner has access to that project. The connection runs with that user's Jira permissions, so issues in projects they can't see won't appear.

</details>

<details>

<summary><strong>A connection that worked has stopped</strong> - Token expired or revoked</summary>

Atlassian API tokens expire on the date set when they were created, and a working Jira connection breaks silently once the token lapses. Tokens that were revoked in Atlassian, or that belonged to a user who lost Jira access, fail the same way.

Create a new token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens), then reopen **Configure Jira**, click **Edit Configuration**, and paste in the new token.

</details>

<details>

<summary><strong>Issues are missing or you can't connect at all</strong> - Permission issue</summary>

Configuring the integration needs an Admin role at the account level. If **Set up** or **Edit Configuration** isn't available, ask an account Admin to make the change.

For which Jira issues appear, the connection uses the token owner's Jira permissions. If a teammate can't find an issue you can see, the token owner may not have access to that project in Jira.

</details>

For questions about how the connection behaves across your account, such as disconnecting Jira or what happens when you remove it, see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Article</th><th>What it covers</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>How to manage integrations</strong></td><td>Change, disconnect, or reconfigure an existing integration</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr><tr><td><strong>How to use planning cards</strong></td><td>Search and link issues from connected tools onto a journey map</td><td><a href="/pages/8b7Oqz3iQ0er7DHD7TSo">/pages/8b7Oqz3iQ0er7DHD7TSo</a></td></tr><tr><td><strong>Set up your first integration</strong></td><td>Choose an integration type and connect your first tool</td><td><a href="/pages/MnIIaFvymKzpE7B98hdU">/pages/MnIIaFvymKzpE7B98hdU</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://helpdesk.smaply.app/integrations/planning-tools/how-to-set-up-the-jira-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.