> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cantina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira

> Connect Jira Cloud to Clarion with an Atlassian service account so agents can create, look up, and search issues during triage.

This guide shows how to connect Jira Cloud to Clarion using an Atlassian service account and OAuth 2.0 client credentials.

> **Note:** **Estimated time:** 10-15 minutes. You need access to:
>
> * A Clarion workspace\*\*
> * Atlassian Administration\*\* for your Jira site
>   \* A service account that can view, search, and create issues in the Jira projects you want Clarion to use

## Prerequisites

Before connecting Jira in Clarion, make sure you have:

* Your Jira site URL, for example `https://example.atlassian.net`
* A Jira service account with access to the relevant projects
* An OAuth 2.0 credential created for that service account
* These credential scopes:
  * `read:jira-work`
  * `write:jira-work`

> **Info:** Clarion uses the service account's client credentials to request short-lived Jira access tokens automatically. You do not need to reconnect the integration just because an access token expires.

***

## Step 1 - Create a Jira service account

1. In **Atlassian Administration**, open **Directory** and create a **service account**.
2. Grant the service account access to **Jira**.
3. Make sure the service account has the Jira project permissions it needs in the projects Clarion will use.

The service account should be able to:

* Search issues
* View issue details
* Create issues in the target project

***

## Step 2 - Create OAuth 2.0 credentials for the service account

1. Open the service account in **Atlassian Administration**.
2. Go to **Credentials**.
3. Create an **OAuth 2.0** credential.
4. Grant only these scopes:
   * `read:jira-work`
   * `write:jira-work`
5. Copy the **Client ID** and **Client secret**.

> **Tip:** Keep the client secret somewhere safe. You will paste it into Clarion during setup.

***

## Step 3 - Connect Jira in Clarion

1. In Clarion, go to **Integrations**.
2. Open **Jira**.
3. Enter:
   * **Site URL**
   * **Client ID**
   * **Client Secret**
   * **Default Project Key** (optional, but recommended)
4. Click **Connect Jira**.

***

## Step 4 - Verify and maintain the connection

After connecting:

1. Review the saved Jira site and client ID.
2. Set or update **Default Project Key** if you want Clarion to fall back to a project automatically.
3. Click **Save** after any changes.
4. Click **Verify Connection** to confirm Clarion can access Jira successfully.
5. Use **Disconnect** if you want to remove Jira access from the workspace.

> **Tip:** Agents can still pass `projectKey` explicitly per tool call. If omitted, Clarion falls back to the configured default project key.

***

## How Jira tools use this integration

When Jira tools are enabled, Clarion can:

* Create issues
* Fetch issue details
* Search issues with JQL

Clarion manages Jira access tokens automatically from the stored client credentials.

***

## Troubleshooting

### "Failed to resolve Jira cloud ID"

Check that **Site URL** is exactly your Jira Cloud URL, for example:

* `https://example.atlassian.net`

Do not include a path such as `/jira`, `/projects`, or `/browse`.

### "Jira credential is missing required scopes"

Recreate or update the OAuth 2.0 credential so it includes:

* `read:jira-work`
* `write:jira-work`

### Verify Connection fails even though the credential is valid

Make sure the service account itself has Jira product access and project-level permissions in the projects Clarion needs to read or create issues in.

### "Project key is required" when creating issues

Set **Default Project Key** in the Jira integration, or pass `projectKey` directly in the Jira tool call.