Skip to main content

Jira

Read and update Jira issues on your Atlassian Cloud site.

Connect it with: Sign in (OAuth), User name and password. Jira's own documentation: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/.

What agents can do​

Connect Jira so the agents working your tasks can reach it. With it connected, they can:

  • Read the Jira issue a task names: description, comments, status, sub-tasks and links.
  • Create Jira issues for follow-up work, and comment with progress or pull request links.
  • Move an issue through its workflow when the work is done.
  • Search with JQL to find related work.
  • Start a Jaah task when an issue is assigned to the Jaah account, mentions it or gets the jaah label, and report back on the issue (Settings > Integrations > Issue trackers > Add tracker).

Before you start​

  • An Atlassian Cloud site (https://your-site.atlassian.net) and an account with access to the Jira projects agents need.
  • Your organization must allow API tokens: an admin can block them in admin.atlassian.com > Security > API token controls.
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Jira​

This is the quickest way in: you sign in to Jira and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for Jira and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Select Connect Jira. Jira's sign-in window opens.
  5. Sign in to Jira if asked, check the access listed, and approve it.
  6. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at Jira yet. Use an API key, or your own OAuth app, until it does.

Scopes Jaah requests​

Jaah asks Jira for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

ScopeWhy Jaah asks for itRequired
read:jira-workRead Jira issues, comments and projectsYes
write:jira-workCreate, comment on and transition Jira issuesYes
read:jira-userLook up Jira users, to assign and mention themYes
read:meKnow who signed in, so the secret shows whose it isYes
offline_accessStay connected: lets Jaah renew access without asking you to sign in againYes

Connect with an API key​

Prefer this when you cannot sign in with Jira — for example a service account, or a token your admin issued. On the Connect screen select Use an API key instead.

Find each value first:

  • Base URL: Your Atlassian site's address, as in your browser when you open Jira: https://your-site.atlassian.net, with nothing after .net. Connect fills it.
  • Account email: The email address of the Atlassian account the API token belongs to (Atlassian > your avatar > Manage account > Email).
  • API token: id.atlassian.com/manage-profile/security/api-tokens > Create API token (or Create API token with scopes, choosing the Jira app): name it Jaah, set an expiry, select Create, then Copy - Atlassian shows it once.
  • Project key (optional): Optional: the Jira project agents work in, the prefix of its issue keys (OAM in OAM-123). Leave blank for a site-wide connection several projects share.

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Jira card.
  2. Name the secret and choose who can use it.
  3. Select Use an API key instead.
  4. Fill in Base URL, Account email, API token, Project key.
  5. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Register your own OAuth app at Jira when your company requires apps it controls, or before this Jaah has an app registered there.

  1. Create an OAuth app in Jira's developer console, https://developer.atlassian.com/console/myapp/ (Jira's documentation).
  2. Set its redirect URI to https://app.jaah.ai/api/credentials/connect/callback (on your own Jaah, its console address followed by /api/credentials/connect/callback).
  3. Give it the scopes in Scopes Jaah requests.
  4. Copy its client ID and client secret.
  5. In Jaah, start a new Jira secret, select Use your own OAuth app, paste both values and select Connect Jira.

The client secret is stored with the connection, encrypted, like any other secret value.

Test the connection​

Select Test on the secret. Jaah calls Jira's API once (GET https://api.atlassian.com/ex/jira/<cloud_id>/rest/api/3/myself) with the stored values, and shows who it answered as, or which value Jira refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

A key connection hands the agent its fields: base_url, email, api_token, project_key.

Tell the agent in your task description which secret to use, for example “use the Jira secret org/jira”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Jira once the test passes. Steps: Replace or delete a secret.
  • Reconnect: when Jira ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Jira's side too, revoke Jaah in Jira's settings, or change the password at Jira or remove the user.

Limitations​

  • A Connect secret reaches one site, the one picked at consent, and agents call it through https://api.atlassian.com/ex/jira/ followed by the secret's Cloud ID rather than the site address. Connect again for another site.
  • Issue tracking (Settings > Integrations > Issue trackers) still needs an API token secret.
  • Jira Server and Data Center are not supported: they use personal access tokens, not Cloud API tokens.
  • Agents act as the account that owns the token: issues and comments are attributed to it. Use a dedicated Atlassian account for agents if you want them separate.
  • API tokens now expire after at most one year; create a new one before it expires.
  • The token reaches every project its account can see; limit the account, or use a token with scopes.
  • A token with scopes works only through https://api.atlassian.com/ex/jira/ followed by the site's cloud ID (read it from https://your-site.atlassian.net/_edge/tenant_info). Jaah's Test and issue tracking do this for you; agents calling Jira themselves must too.
  • Confluence is not covered here: use the Atlassian card for Confluence pages.
  • Agents can do only what the connected Jira account and its granted scopes allow.

Troubleshooting​

Test says the credentials were rejected (401)

Account email does not match the token's account, or the token expired or was revoked. Create a new token at id.atlassian.com and select Replace.

Test cannot reach the site or answers 404

Base URL is not your site's root. Use https://your-site.atlassian.net with nothing after it.

Test passes but agents get 403 on a project

The account lacks Browse projects permission there. Ask a Jira admin to add it to the project.

Test fails with 403 for every request

Your organization blocks API tokens or requires them from allowed IPs only. Ask an admin to check admin.atlassian.com > Security.

Connect ends with no organisation or site for this sign-in

No site was chosen on Atlassian's consent page. Select Connect again and pick the site agents should reach.

Still stuck? Select Test and read the result: it names the value Jira refused and the status it answered.

FAQ​

Can I use an API token with scopes?

Yes. Create it for the Jira app only; one Jira token is all Jaah needs. Jaah reaches Jira through Atlassian's gateway with it.

Should I connect or use an API token?

Connect is quicker and renews itself. Use an API token for issue tracking, or when your organization blocks third-party apps.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Jira account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.