# Jira Cloud

[Jira Cloud](https://www.luciq.ai/integrations/jira)

Allow your users and beta testers to report bugs and send feedback directly from your app and have them automatically logged into your Jira project. Luciq offers a **two-way integration** when the integration is done through Jira, meaning that the status and comments on the Jira ticket will also be reflected on the bug report on your Luciq dashboard.

***

Luciq supports five ways to authenticate with Jira Cloud. For most users, we recommend **OAuth 2.0**.

When you create the integration, the wizard's **Authenticate** step shows an **Authentication type** dropdown with five options, listed below in the same order as the dropdown:

* **OAuth 2.0 (Recommended)** — one-click sign-in with your Atlassian account; tokens refresh automatically; no admin setup required in most orgs.
* **OAuth service accounts** — programmatic integration tied to a service account; no browser flow; scopes are controlled centrally on the Atlassian admin dashboard.
* **Service accounts with scoped API Tokens** — also tied to a service account with no browser flow; a single non-rotating token whose scopes are baked in at creation time.
* **Basic Authentication** — your Atlassian email and a classic API token. Still supported, but Atlassian now enforces a maximum 1-year expiration on every token, so you'll need to rotate it annually.
* **Luciq Add-on (Legacy)** — our Atlassian Marketplace Connect app. No longer receiving updates; see the dedicated section below.

After picking an authentication type, the rest of the wizard (Set up → Test → Finish) is the same across all options — see [Set up, test, and finish](#set-up-test-and-finish) at the bottom of this page.

#### OAuth 2.0 (Recommended)

Best for most users — one-click browser sign-in, tokens refresh automatically, no admin setup required in most Atlassian organizations.

{% hint style="warning" %}
Some Atlassian organizations require an admin to approve new OAuth apps before non-admins can connect. If you see *"Your site admin must authorize this app"*, ask your Atlassian admin to approve `luciq-jira-oauth-integration` in **admin.atlassian.com → Apps → User requests**, or switch to one of the service-account options below (which don't go through OAuth approval).
{% endhint %}

{% stepper %}
{% step %}
**Start the OAuth flow**

In your Luciq dashboard, go to **Settings → Integrations → Jira Cloud**, pick **OAuth 2.0 (Recommended)** from the **Authentication type** dropdown, then click **Authenticate**.
{% endstep %}

{% step %}
**Sign in to Atlassian**

You'll be redirected to Atlassian. Sign in as the user you want forwarding to run as, then approve the requested permissions.

{% hint style="info" %}
If you're already signed in to Atlassian in your browser, that session is used automatically — Atlassian won't show a sign-in screen. To connect with a different account, sign out of Atlassian first ([id.atlassian.com](https://id.atlassian.com) → your avatar → **Log out**), then restart the OAuth flow.
{% endhint %}
{% endstep %}

{% step %}
**Pick a Jira site**

If you have access to multiple Atlassian sites, pick the one you want forwarding to go to.
{% endstep %}
{% endstepper %}

Continue with [Set up, test, and finish](#set-up-test-and-finish).

#### OAuth service accounts

For teams that want a programmatic integration tied to a service account rather than to an individual user. Like OAuth 2.0, this method uses OAuth under the hood — but with Atlassian's `client_credentials` grant (no browser dance) and a service-account-owned OAuth client whose **scopes are managed centrally on the Atlassian admin dashboard**. Changing scopes doesn't require rotating the Client ID or Client Secret.

{% stepper %}
{% step %}
**Create a service account in Atlassian (one-time, by your org admin)**

In [admin.atlassian.com](https://admin.atlassian.com), go to **Directory → Service accounts → Create service account**, grant it product access to Jira, then add it to a group with **Create Issues** and **Browse Projects** permission on your target project(s).
{% endstep %}

{% step %}
**Generate OAuth credentials**

From the service account's credentials page, create an OAuth 2.0 client. Atlassian returns a **Client ID** and **Client Secret**. Grant the client these scopes (manageable later from the same page):

* `read:jira-work`
* `write:jira-work`
* `read:jira-user`
* `manage:jira-webhook`
* `read:field:jira`
  {% endstep %}

{% step %}
**Connect in Luciq**

In your Luciq dashboard, go to **Settings → Integrations → Jira Cloud**, pick **OAuth service accounts** from the **Authentication type** dropdown, then paste the **Client ID** and **Client Secret**.
{% endstep %}

{% step %}
**Pick a Jira site**

If the service account has access to multiple Atlassian sites, pick the one you want forwarding to go to.
{% endstep %}
{% endstepper %}

Continue with [Set up, test, and finish](#set-up-test-and-finish).

#### Service accounts with scoped API Tokens

Same idea as **OAuth service accounts** — credentials are tied to a service account and there's no browser flow — but instead of an OAuth client, you paste a single non-rotating **scoped API token**. **The token's scopes are fixed at creation time**: changing them requires creating a new token. Choose this option if you'd rather hold a single secret than manage an OAuth client.

{% stepper %}
{% step %}
**Create a service account in Atlassian (one-time, by your org admin)**

In [admin.atlassian.com](https://admin.atlassian.com), go to **Directory → Service accounts → Create service account**. Add the new account to a Jira group that has **Create Issues** and **Browse Projects** permission on your target project(s).
{% endstep %}

{% step %}
**Create a scoped API token for the service account**

From the service account's credentials page, click **Create scoped API token** and grant these scopes:

* `read:jira-work`
* `write:jira-work`
* `read:jira-user`
* `manage:jira-webhook`
* `read:field:jira`

Atlassian only shows the token once — copy it immediately.
{% endstep %}

{% step %}
**Connect in Luciq**

In your Luciq dashboard, go to **Settings → Integrations → Jira Cloud**, pick **Service accounts with scoped API Tokens** from the **Authentication type** dropdown, then paste the token and your site URL (e.g. `https://yourcompany.atlassian.net`).
{% endstep %}
{% endstepper %}

Continue with [Set up, test, and finish](#set-up-test-and-finish).

#### Basic Authentication

Authenticate with your Atlassian email and a classic API token.

{% hint style="warning" %}
Atlassian now enforces a maximum 1-year expiration on every API token. Tokens created before **December 15, 2024** are being retroactively expired between **March 14 – May 12, 2026**. If you use this method, plan for annual token rotation — or pick **OAuth 2.0 (Recommended)** above to avoid manual rotation entirely. If your forwarding has already stopped, contact Luciq support.
{% endhint %}

{% stepper %}
{% step %}
**Enter Jira credentials**

Pick **Basic Authentication** from the **Authentication type** dropdown, then insert your **Jira Email**, **API Token** (which can be retrieved from [here](https://id.atlassian.com/manage/api-tokens)), and **URL**.
{% endstep %}
{% endstepper %}

Continue with [Set up, test, and finish](#set-up-test-and-finish).

#### Luciq Add-on (Legacy)

{% hint style="danger" %}
This option is legacy — it relies on our Atlassian Marketplace **Connect** app, which we're no longer pushing updates to. Existing integrations continue to work, but for new setups please pick one of the four authentication methods above.
{% endhint %}

The Luciq Add-on integration is installed from the Atlassian Marketplace and configured from the Jira side rather than from Luciq. End-to-end setup steps are documented in the [Through Jira Add-On](#through-jira-add-on) section at the top of this page — picking **Luciq Add-on (Legacy)** from the **Authentication type** dropdown is the Luciq-side counterpart.

{% stepper %}
{% step %}
**Add your Jira board link**

To set up your Jira Cloud integration, simply add the link to your Jira board, where you will see your incoming reports.
{% endstep %}

{% step %}
**Explore apps on your Jira board**

On your Jira board, from the Apps section, click on "Explore more apps".
{% endstep %}

{% step %}
**Search for Luciq**

Search "Luciq" from the search window and click on the add-on.
{% endstep %}

{% step %}
**Install the Add-On**

After selecting our Add-On app, click on the Get App button.
{% endstep %}

{% step %}
**Configure the Add-On**

Click on "Configure" which is found within the prompt after installing the add-on from Jira's side.
{% endstep %}

{% step %}
**Login to Luciq**

Login using your Luciq dashboard credentials in order to have it synced with your dashboard.
{% endstep %}

{% step %}
**Select project settings**

Select the project, issue type, assignee, and any custom fields you have setup.
{% endstep %}

{% step %}
**Test the integration**

At this point, we just need to test your integration so that we're sure everything is working smoothly.
{% endstep %}

{% step %}
**Finish setup**

All done! Your integration is now set up and ready to go. From this final page, you can allow automatic forwarding (this can be reconfigured at any time) as well as synced status.
{% endstep %}
{% endstepper %}

#### Set up, test, and finish

After authenticating with any of the four methods above, the wizard takes you through the same final steps:

{% stepper %}
{% step %}
**Pick project and map fields**

Pick the **project** you want to forward to, the **issue type**, and the **assignee**. You can map Luciq fields to Jira custom fields and choose which information is forwarded from your Luciq dashboard to Jira.
{% endstep %}

{% step %}
**Test the integration**

Click **Test** to confirm Luciq can create an issue in your target project. This validates that the credentials, project, issue type, and any required custom field mappings are correct.
{% endstep %}

{% step %}
**Finish setup and enable two-way sync**

All done! From this final page, you can allow two-way integration (if Luciq is already installed on your Jira dashboard via the Atlassian Marketplace add-on) and allow for automatic forwarding. These can be reconfigured at any time.
{% endstep %}

{% step %}
**Start receiving issues**

Start receiving issues on the spot on your Jira dashboard.

With this integration, bugs and feedback can be converted manually into issues on Jira with just a click.
{% endstep %}
{% endstepper %}

***

### Mapping Custom Fields

This section covers how to map Jira custom fields to fields from the Luciq dashboard.

{% stepper %}
{% step %}
**Create the custom field in Jira**
{% endstep %}

{% step %}
**Choose a type**

Choose a type for the field you've created in the previous step.
{% endstep %}

{% step %}
**Reconfigure the Jira integration**

Reconfigure your Jira integration.
{% endstep %}

{% step %}
**Map fields**

Map the Jira custom fields to the corresponding Luciq fields (make sure they have the same type).
{% endstep %}

{% step %}
**Test your integration**

Test your integration.
{% endstep %}

{% step %}
**Finish**

All done!
{% endstep %}

{% step %}
**Forwarded bug appearance**

This is how the forwarded bug report should look on Jira.
{% endstep %}
{% endstepper %}

***

### Priority Sync

Once you enable two-way sync for the priority, any change done to the priority field in our dashboard will be reflected in Jira and vice versa.

Two-way sync for the priority will only work if you are using the default priorities in Jira. If you are using custom priorities, the bug will be forwarded to Jira successfully, but the priority will not be synced.

### **Priority Mapping**

| Luciq Priorities | Jira Priorities |
| ---------------- | --------------- |
| NA               | Medium          |
| Trivial          | Lowest          |
| Minor            | Low             |
| Major            | High            |
| Blocker          | Highest         |


---

# Agent Instructions: 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:

```
GET https://docs.luciq.ai/product-guides-and-integrations/integrations/jira-cloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.