--- title: Connect Jira canonical: "https://agentbarn.dev/guides/integrations/jira" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-13T13:41:42.000Z" author: Agent Barn description: "Connect Jira Cloud to an Agent Barn Agent with a scoped or non-scoped API token, resolved Cloud ID, least-privilege project permissions, and validation." tags: [Integrations, How-to, "Jira administrators, Agent operators, and Organization administrators", Jira, Atlassian, Jira API token, scoped token, Cloud ID, jira-work profile, Browse Projects, Jira permissions, shared credential] categories: [Guides, Integrations] --- - Integrations - 10–15 minutes - Requires a Jira Cloud API token Connect Jira to let an Agent search issues, inspect projects and boards, work with sprints, and, when permitted, create, update, transition, or comment on issues. Agent Barn stores the Jira API token as an encrypted Agent Secret, and creates an `aai-cli` profile named `jira-work` when the Agent starts. **Authorization boundary** The Atlassian account’s Jira product and project permissions determine what the Agent can do. Connecting a site URL in Agent Barn does not reduce permissions already granted to that account. ## Connection model 1. Atlassian account 2. API token 3. Encrypted Agent Secret 4. jira-work profile 5. Jira Cloud The credential authenticates the Agent. The Jira Skill supplies the `aai-cli` workflows the Agent uses against that credential. ## Before you begin You need: - A Jira Cloud site - An Atlassian account with Jira product access - Permission to create an API token - The Jira site URL - The email address associated with the token - Access to configure the Agent - `agent.update` and `agent.secret.manage` permissions - Lifecycle permission when connecting a running Agent Decide whether the Agent needs read-only project access, issue creation, issue updates and transitions, comments, or board and sprint management. Use a dedicated Atlassian account or service identity when possible. ## Understand the credential fields | Field | Purpose | | --- | --- | | Site URL | Identifies the Jira Cloud tenant | | Authentication type | Selects scoped or non-scoped token routing | | Email | Atlassian account associated with the token | | API token | Authenticates the account | | Cloud ID | Resolved and stored internally for scoped tokens | Use the base site URL: ``` https://example.atlassian.net ``` Do not enter a Jira route or REST path: ``` https://example.atlassian.net/jira https://example.atlassian.net/rest/api/3 ``` Agent Barn builds the required API paths. ## Choose an authentication type Agent Barn supports two Jira token paths. Both use Basic authentication with the account email and API token; the difference is the API host. ### Non-scoped token Standard Atlassian account API token, sent directly to your Jira site. ``` https://example.atlassian.net/rest/api/3/... ``` Choose this when the token is intended for direct Jira site API access. ### Scoped token Sent through Atlassian’s API Gateway using the resolved Cloud ID. ``` https://api.atlassian.com/ex/jira/{cloud_id}/rest/api/3/... ``` Choose this when the token must be sent through Atlassian’s API Gateway. **Important** Agent Barn resolves the Cloud ID automatically from the Jira site. Do not paste a Cloud ID into the credential form. ## How Cloud ID resolution works For a scoped token, Agent Barn requests tenant metadata from the site and stores the returned Cloud ID with the encrypted credential. 1. **Jira site URL** The base tenant URL saved with the credential 2. **/\_edge/tenant\_info** Agent Barn requests the site’s tenant metadata 3. **Atlassian Cloud ID** Stored with the encrypted credential 4. **api.atlassian.com/ex/jira/{cloud\_id}** The gateway host used by scoped tokens at runtime Cloud ID lookup occurs when the credential is saved, and again during live validation when required. **Scoped token** Validate every scoped Jira credential before using it in production. If the Cloud ID is missing, Agent Barn cannot generate the `jira-work` runtime profile. ## Plan Jira permissions Grant permissions based on the intended workflow. | Agent workflow | Common Jira permission requirement | | --- | --- | | List or read issues | Browse Projects | | View boards and sprints | Browse Projects, and access to the underlying project | | Create issues | Create Issues | | Update issue fields | Edit Issues | | Add comments | Add Comments | | Transition issues | Transition Issues | | Assign issues | Assign Issues | | Create or manage sprints | Manage Sprints | | Add issues to sprints | Manage Sprints, and the appropriate issue permissions | The exact Jira permission scheme can vary by project. Start with Browse Projects, then add narrowly scoped permissions for documented write workflows. **Important** Agent Barn validates the Jira identity and product access. It does not evaluate every project permission scheme. ## Create the Jira API token Using the intended Atlassian account: 1. Open the account’s security settings. 2. Go to API token management. 3. Create the appropriate token type. 4. Give it a descriptive name, such as `Agent Barn: Support Agent`. 5. Set an expiration or rotation plan when available. 6. Copy the token. 7. Record whether it is scoped or non-scoped. **Security** Do not use the Atlassian account password. Treat the API token as a secret, and never paste it into a Template, Skill, prompt, or Agent conversation. ## Prepare the Jira account Before connecting: 1. Confirm that the account can sign in to the Jira site. 2. Confirm that it has Jira product access. 3. Open each intended project. 4. Verify the project permissions required by the Agent. 5. Remove access to unrelated projects where possible. 6. Test one read-only Jira action with the account. The API token inherits the account’s effective Jira access. ## Connect Jira in Agent Barn 1. Stop the Agent, or begin the web interface’s restart-aware edit flow. 2. Open the Agent. 3. Go to **Configuration**. 4. Select **Keys & integrations**. 5. Select **Edit**. 6. Add **Jira** under Integration credentials. 7. Choose **Enter credentials**. 8. Enter the base Jira site URL. 9. Select **Scoped token** or **Non-scoped token**. 10. Enter the Atlassian account email. 11. Paste the API token. 12. Apply the configuration. 13. Restart the Agent if it was running. 14. Validate the credential. 15. Test project and issue access. The API token is hidden after it is saved. ### Use a Shared Jira Credential Jira is supported by Organization Shared Credentials. To attach one: 1. Open the Agent’s integration configuration. 2. Select Jira. 3. Choose **Use shared credential**. 4. Select the named Jira credential. 5. Apply the configuration. 6. Restart the Agent. 7. Validate and test the connection. **Shared credential** The Agent stores a reference to the Shared Credential instead of another encrypted token copy. An Agent can use either a manual Jira credential or a Shared Jira Credential, not both. See [Use shared credentials](/guides/integrations/shared-credentials) for the complete lifecycle. ### Assign the Jira Skill The credential provides authentication. The Jira Skill provides the Agent with detailed `aai-cli` workflows. If the active Template requires Jira: 1. Open the Agent’s **Skills** configuration. 2. Confirm that the Jira Skill is assigned. 3. Confirm the pinned Skill version. 4. Save the Agent configuration. 5. Start the Agent. An explicit Template requirement must be satisfied by an explicit Skill assignment. ## Validate the credential 1. Open **Keys & integrations**. 2. Find **Jira**. 3. Select **Validate**. 4. Confirm the expected account identity. 5. Resolve any errors. 6. Continue with project-level verification. For a non-scoped token, Agent Barn requests `/rest/api/3/myself` on your site. For a scoped token, it requests the same path through the Atlassian gateway host. Validation confirms that the site is reachable, the email and token authenticate, the account has Jira product access, the Jira account is active, and the expected identity is returned. ``` { "validation_status": "valid", "validation_identity": "Support Agent (agent@example.com)", "validation_error": null, "missing_scopes": [] } ``` **Important** A successful result does not prove that the account can access a specific project. Continue with project-level verification. ## Verify access ### Verify project access Ask the Agent: ``` List the Jira projects available to the connected account. ``` The underlying command is: ``` aai-cli jira projects list --limit 20 --profile jira-work ``` Review the result for missing intended projects, unexpected projects, or incorrect account scope. If unexpected projects appear, reduce the Atlassian account’s Jira permissions. ### Verify issue access Use a known project key: ``` aai-cli jira issues list \ --project SUPPORT \ --limit 10 \ --profile jira-work ``` Jira issue listing requires at least one filter. Do not run an unbounded issue query. Other useful filters include: ``` --status "To Do,In Progress" --assignee me --sprint current --updated-since 7d ``` Read a known non-sensitive issue: ``` aai-cli jira issues get SUPPORT-123 --profile jira-work ``` Confirm that the returned issue belongs to an intended project, and that sensitive fields follow organizational policy. ### Verify boards and sprints ``` aai-cli jira boards list \ --project SUPPORT \ --limit 10 \ --profile jira-work ``` ``` aai-cli jira sprints list \ --board 42 \ --state active \ --profile jira-work ``` Board visibility depends on the connected account’s access to the underlying Jira projects. ### Verify write access safely Only test writes when the Agent is intended to perform them. Use a designated test project or issue. ``` aai-cli jira issues comments create SUPPORT-123 \ --body "Agent Barn integration verification." \ --profile jira-work ``` ``` aai-cli jira issues create \ --project SUPPORT \ --summary "Agent Barn integration verification" \ --description "Temporary test issue." \ --profile jira-work ``` Remove or close test data after verification. **Verification** Test reads before writes. A valid token can still lack Add Comments, Create Issues, Edit Issues, Transition Issues, or Manage Sprints. ## Runtime behavior When the Agent starts, Agent Barn: 1. Decrypts the Jira credential. 2. Resolves the scoped-token Cloud ID when needed. 3. Stores the API token in the runtime secret store. 4. Creates the `jira-work` profile. 5. Mounts eligible Jira Skill instructions. 6. Adds the Jira site and connected email to the integration context. For a non-scoped token: ``` [profiles.jira-work] auth_type = "basic_api_token" site_url = "https://example.atlassian.net" email = "agent@example.com" api_token_secret = "jira.api_token" ``` For a scoped token, the profile uses the Atlassian gateway host with the resolved Cloud ID. **Runtime** The Agent should not ask a user to paste Jira credentials into a conversation. The runtime supplies the profile and token automatically. ### Scoped-token save behavior When a scoped credential is saved, Agent Barn tries to resolve and store its Cloud ID. If lookup temporarily fails, the encrypted credential can still be stored without the Cloud ID, but runtime profile generation skips the Jira profile until the credential is saved again successfully. Always validate a scoped credential after saving it. If validation reports a Cloud ID error: 1. Confirm the site URL. 2. Confirm that Agent Barn can reach the site. 3. Save the credential again. 4. Validate it. 5. Restart the Agent. ## Rotate the Jira token 1. Create a replacement token in Atlassian. 2. Record whether it is scoped or non-scoped. 3. Stop the Agent, or begin a restart-aware edit. 4. Open **Keys & integrations**. 5. Enter the complete replacement Jira credential. 6. Re-enter the site URL, authentication type, and email. 7. Apply and restart. 8. Validate the new token. 9. Test project and issue access. 10. Revoke the old token. Stored credential values cannot be retrieved or partially edited. ### Change the Jira account 1. Prepare an API token for the replacement Atlassian account. 2. Confirm its product and project permissions. 3. Replace the complete Jira credential in Agent Barn. 4. Apply and restart. 5. Validate the returned identity. 6. Test intended projects. 7. Revoke the previous account’s token when appropriate. Review project access carefully, because the new account may have a different permission scheme. ## Remove Jira access 1. Stop the Agent, or begin a restart-aware edit. 2. Identify any assigned Skill requiring `jira`. 3. Remove or replace that Skill when permitted. 4. Open **Keys & integrations**. 5. Select **Remove** for Jira. 6. Apply the configuration. 7. Restart the Agent. 8. Confirm that Jira is unavailable. 9. Revoke the API token in Atlassian. Agent Barn rejects removal while a remaining assigned Skill requires Jira. ## API reference ### Add a non-scoped Jira credential The Agent must be stopped. ``` PATCH /api/v1/organizations/{organization_id}/agents/{agent_id} Content-Type: application/json ``` ``` { "secrets": [ { "provider": "jira", "content": { "site_url": "https://example.atlassian.net", "use_scoped_token": false, "email": "agent@example.com", "api_token": "REDACTED" } } ] } ``` ### Add a scoped Jira credential ``` { "secrets": [ { "provider": "jira", "content": { "site_url": "https://example.atlassian.net", "use_scoped_token": true, "email": "agent@example.com", "api_token": "REDACTED" } } ] } ``` Do not submit `cloud_id`. Agent Barn resolves and enriches that field internally. Every token value in these examples is redacted; supply your own. ### Attach a Shared Jira Credential ``` { "shared_credentials": [ { "shared_credential_id": "3fd08cf5-59c5-494b-9449-a0413109a0ca" } ] } ``` ### Validate Jira ``` POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/jira/validate ``` Validation requires `agent.secret.manage`. ### Remove Jira ``` { "removed_secret_providers": [ "jira" ] } ``` ## Troubleshooting ### Validation says “Invalid email or API token” Check the pair and the token type Check that: - The email belongs to the token’s Atlassian account - The token was copied completely - The correct authentication type was selected - The token has not expired or been revoked - The site URL belongs to the intended Atlassian tenant Replace the complete credential and retry. ### Validation says the account has no Jira product access Product access is separate The Atlassian account exists but does not have Jira product access for the site. Grant the appropriate product access, or use another account. ### Validation says the Jira account is inactive Reactivate or replace the account Reactivate the Atlassian account, or connect an active account. ### Agent Barn cannot resolve the Cloud ID Check the base site URL Confirm that the base site URL is correct and reachable: ``` https://example.atlassian.net ``` Do not include a Jira route or REST API path. Save and validate the scoped credential again. ### The runtime logs say cloud\_id missing Saved before discovery succeeded The scoped credential was saved when Cloud ID discovery failed. Re-enter the complete credential, save it again, validate it, and restart the Agent. ### Validation passes, but no projects appear Identity is not project access Identity validation does not check project permissions. Grant Browse Projects for the intended projects, and verify that project security settings permit the account. ### One project works and another returns 404 Per-project permission schemes The connected account likely lacks Browse Projects or issue security access in the second project. Review that project’s permission scheme. ### Issue listing returns an unbounded-query error At least one filter is required Provide at least one filter, such as: ``` --status "To Do,In Progress" --assignee me --sprint current --updated-since 7d ``` ### Issue reads work, but comments fail Add Comments is separate The account probably lacks Add Comments in that project. Grant the permission only if the Agent should comment. ### Issue reads work, but transitions fail Permission or workflow state The account may lack Transition Issues, or the requested transition may not be valid from the issue’s current workflow state. ### Boards or sprints are missing Board access follows project access Confirm access to the underlying software project and board. Sprint modification additionally requires Manage Sprints. ### A Shared Credential conflicts with a manual Jira credential One source per provider An Agent can use only one Jira credential source. Remove the manual credential before attaching the Shared Credential, or replace the Shared attachment with a manual credential. ### Jira was connected but the Agent cannot use it Restart, Skill, profile, or permissions Check that: - The Agent restarted after saving - The Jira Skill is assigned when required - The expected Skill version is pinned - The `jira-work` profile was generated - Validation returns the expected identity - The Atlassian account has project access - Startup logs do not report a missing Cloud ID ## Recommended practices - Use a dedicated Atlassian identity for production Agents - Grant Jira product access only where required - Restrict the account to intended projects - Begin with Browse Projects - Add write permissions one workflow at a time - Use separate credentials for Agents with different project boundaries - Select the correct scoped-token setting - Validate every scoped credential - Test reads before writes - Use a designated project for write verification - Rotate tokens on a documented schedule - Revoke old and unused tokens - Never place Jira tokens in Templates, Skills, prompts, or conversations - Review Jira permission schemes when an Agent’s responsibilities change ## Next steps Continue to [Connect Confluence](/guides/integrations/confluence) to configure an Atlassian credential for the intended Confluence spaces and page operations. - [Manage Agent credentials](/guides/integrations/credentials) - [Use shared credentials](/guides/integrations/shared-credentials) - [Work with Skills](/guides/templates-and-skills/skills)