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

# Jira (Direct OAuth)

Connect Jira Cloud to Athena so each member can search issues, read tickets
and comments, and explore projects as their **own Atlassian identity**. Jira
project permissions and issue-level security apply unchanged — Athena sees
exactly what you can see in Jira, and nothing is shared through a service
account or personal access token.

<Info>
  Setup is two steps, done by two different people: your **Atlassian
  administrator** registers an OAuth app in the Atlassian developer console,
  then an **Athena workspace admin** saves that app once for the whole
  workspace. Members can only connect after both are done. The Jira
  integration is currently in an admin-only rollout — contact
  [team@athenaintel.com](mailto:team@athenaintel.com) to enable it for your workspace.
</Info>

## Step 1 — Register an OAuth app in Atlassian (Atlassian admin)

One app registration serves every user and every Jira site in your
organization — Atlassian resolves which site a request targets at runtime.

1. Open **[developer.atlassian.com](https://developer.atlassian.com)** → your
   profile icon → **Developer console** → **Create** → **OAuth 2.0
   integration**. Name it e.g. `Athena`.
2. When asked about the grant type, choose **account-level grants** (not
   resource-restricted). A member's single consent can then cover several Jira
   sites, and re-connecting adds new sites to the same grant. This choice is
   made at creation and cannot be changed later.
3. **Permissions** — add both the **Jira API** and the **User Identity API**,
   then enable these scopes:

   ```text theme={null}
   read:jira-work write:jira-work read:jira-user read:me offline_access
   ```

   `read:me` lets Athena identify who connected; `offline_access` keeps the
   connection alive without re-prompting members. Atlassian forces every
   member to re-consent if the scope set changes later, which is why the full
   set is requested up front — write access stays gated inside Athena until
   write features are enabled.
4. **Authorization → Configure** — set the callback URL:

   ```text theme={null}
   https://api.athenaintel.com/api/direct-connectors/jira_direct/oauth/callback
   ```

   For private/VPC deployments, replace `api.athenaintel.com` with your
   environment's Athena API host. Atlassian requires an exact match; if the
   console only accepts one callback URL, register a separate app per Athena
   environment.
5. **Distribution → Enable sharing** and complete the form (vendor details and
   a privacy-policy URL). Without sharing, only the app's creator can connect —
   everyone else gets an Atlassian error. Until the app passes Atlassian's
   optional review, members see a "not yet reviewed by Atlassian" note on the
   consent screen; that's expected for private integrations.
6. From **Settings**, copy the **Client ID** and **Secret** and hand them to
   your Athena workspace admin through a secure channel.

<Info>
  If your Atlassian organization uses the **"Block user apps"** security
  control, an Atlassian org admin must authorize the app (Atlassian
  Administration → Apps → Connected apps) before members can consent —
  otherwise the consent screen shows an admin-approval notice and never
  returns to Athena.
</Info>

## Step 2 — Enable Jira in Athena (workspace admin, once)

Open **[Workspace Settings → Treasury →
Integrations](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integrations)**
and add a new integration:

| Field             | Value                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| **Provider**      | `jira_direct`                                                                                               |
| **Auth method**   | `oauth2`                                                                                                    |
| **Config**        | Pre-filled with Atlassian's authorize/token endpoints — paste the **Client ID** into `connection.client_id` |
| **Client Secret** | From step 1.6 (write-only — leave blank when editing to keep the current one)                               |

Leaving `scopes` empty in the config uses Athena's defaults (the set from
step 1.3). Enable the integration and save. Secrets are encrypted at rest and
never returned to the browser.

## Step 3 — Connect your account (each member)

1. Navigate to
   **[Integrations](https://app.athenaintel.com/dashboard/integrations/)** and
   click **Connect** on the **Jira (Direct OAuth)** card.
2. A popup opens Atlassian's consent screen. Pick your Jira site and approve.
   Athena custodies your encrypted tokens server-side and automatically
   registers every Jira site in your grant — there is no picker step.
3. Have more than one Jira site? Click **Connect** again and select the next
   site — Atlassian adds it to your existing grant.

Once connected, the **Jira toolkit** lets agents search issues with JQL, read
issues and their comments, list your projects, and inspect workflow
transitions. Every Jira tool asks for your approval before it runs.

## Token lifecycle & troubleshooting

* **Everything is per-user.** Results always reflect *your* Jira permissions,
  and any future writes are attributed to you.
* **"Jira authentication failed — reconnect."** Atlassian invalidates
  connections after 90 days of inactivity, on password changes, on SSO
  migrations, and when you revoke access at
  [id.atlassian.com → Connected apps](https://id.atlassian.com/manage-profile/apps).
  Reconnecting from the Integrations page fixes all of these.
* **Missing results from some projects?** Atlassian data-security policies can
  block apps from specific projects — content from those projects is silently
  filtered rather than surfaced as an error. Check with your Atlassian admin.
* **Removed a site from your grant?** Athena automatically retires that site's
  connection; re-consenting for the site restores it.