Skip to main content
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.
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.

​
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 → 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:
    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:
    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.
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.

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

Open Workspace Settings → Treasury → Integrations and add a new integration: 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 and click Connect on the Jira card.
  2. A popup opens Atlassian’s consent screen. It names the site it will install on (“Install app on your-site.atlassian.net”) and lists the Jira permissions being granted — approve it. Athena custodies your encrypted tokens server-side and registers every Jira site in the grant, so there is no picker step on the Athena side.
  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. These are read-only and run without an approval prompt; your Jira permissions still bound every result.

​
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. 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.
  • “Atlassian … returned no Jira sites for the grant.” The connect is refused rather than saved, because a grant with no site cannot answer a single question. The message names the actual cause, and there are three:
    • No Jira scopes were granted — the OAuth app has no Jira permission. In developer.atlassian.com open the app → Permissions → Jira API → Configure, and make sure read:jira-work, write:jira-work and read:jira-user are checked on the Classic scopes tab.
    • Jira scopes granted, but no sites came back — the token is bound to no site. Consent succeeding does not mean the app can reach one. Two causes, in order of likelihood: Atlassian’s discovery index came back empty for a grant that should be able to reach your site. Rather than chase it in Atlassian admin, pin the site: a workspace admin sets connection.site_url on the Jira integration (Workspace Settings → Treasury → Integrations) to your Jira host, e.g. your-site.atlassian.net. Athena then resolves the site directly and verifies the connection against Jira before accepting it — so if Jira does refuse, you get Jira’s own error naming the real problem instead of a generic “no sites”. To confirm the cause first, open id.atlassian.com → Connected apps as the connecting user: that screen lists the sites your grant covers. If Athena lists no site, the app is not installed on a site — which is a separate thing from scopes or licensing, and is why the connection can carry full Jira permissions and still reach nothing.
    • Sites came back, but none expose Jira — the app installed on a site without Jira. Reconnect and choose one where Jira Cloud is active.