How to set up the Jira integration

Connect Jira so your team can link issues to the journey-map steps they affect.

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.

In this guide

1. Set up the Jira integration

2. Verify the setup

3. Use Jira in planning cards

4. Troubleshooting

Set up the Jira integration

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.

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.

1

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.

Configure Jira, empty form

2

Create an API token in Atlassian

In a new tab, go to 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.

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.

3

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.

4

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.

---

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

Connection established

If you don't see the green confirmation, check the 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.

---

Troubleshooting

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

Connection Error or the connection won't save - Connection issue

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.

No items found when adding a planning card - Search issue

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.

A connection that worked has stopped - Token expired or revoked

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, then reopen Configure Jira, click Edit Configuration, and paste in the new token.

Issues are missing or you can't connect at all - Permission issue

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.

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.

Still not working? Contact support at [e-mail]

---

Related topics

How to manage integrations

Change, disconnect, or reconfigure an existing integration

How to use planning cards

Search and link issues from connected tools onto a journey map

Set up your first integration

Choose an integration type and connect your first tool