Integrations

On this page

Connection model
Before you begin
Credential fields
Choose an authentication type
Cloud ID resolution
Plan Jira permissions
1. Create the API token
2. Prepare the Jira account
3. Connect Jira
4. Validate the credential
5. Verify access
Runtime behavior
6. Rotate the token
7. Remove Jira access
API reference
Troubleshooting
Recommended practices
Next steps

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.

Connection model

Atlassian account
API token
Encrypted Agent Secret
jira-work profile
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.

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.

Jira site URL The base tenant URL saved with the credential
/_edge/tenant_info Agent Barn requests the site’s tenant metadata
Atlassian Cloud ID Stored with the encrypted credential
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.

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.

Create the Jira API token

Using the intended Atlassian account:

Open the account’s security settings.
Go to API token management.
Create the appropriate token type.
Give it a descriptive name, such as Agent Barn — Support Agent.
Set an expiration or rotation plan when available.
Copy the token.
Record whether it is scoped or non-scoped.

Prepare the Jira account

Before connecting:

Confirm that the account can sign in to the Jira site.
Confirm that it has Jira product access.
Open each intended project.
Verify the project permissions required by the Agent.
Remove access to unrelated projects where possible.
Test one read-only Jira action with the account.

The API token inherits the account’s effective Jira access.

Connect Jira in Agent Barn

Stop the Agent, or begin the web interface’s restart-aware edit flow.
Open the Agent.
Go to Configuration.
Select Keys & integrations.
Select Edit.
Add Jira under Integration credentials.
Choose Enter credentials.
Enter the base Jira site URL.
Select Scoped token or Non-scoped token.
Enter the Atlassian account email.
Paste the API token.
Apply the configuration.
Restart the Agent if it was running.
Validate the credential.
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:

Open the Agent’s integration configuration.
Select Jira.
Choose Use shared credential.
Select the named Jira credential.
Apply the configuration.
Restart the Agent.
Validate and test the connection.

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:

Open the Agent’s Skills configuration.
Confirm that the Jira Skill is assigned.
Confirm the pinned Skill version.
Save the Agent configuration.
Start the Agent.

An explicit Template requirement must be satisfied by an explicit Skill assignment.

Validate the credential

Open Keys & integrations.
Find Jira.
Select Validate.
Confirm the expected account identity.
Resolve any errors.
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 ([email protected])",
  "validation_error": null,
  "missing_scopes": []
}

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.

Runtime behavior

When the Agent starts, Agent Barn:

Decrypts the Jira credential.
Resolves the scoped-token Cloud ID when needed.
Stores the API token in the runtime secret store.
Creates the jira-work profile.
Mounts eligible Jira Skill instructions.
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 = "[email protected]"
api_token_secret = "jira.api_token"

For a scoped token, the profile uses the Atlassian gateway host with the resolved Cloud ID.

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:

Confirm the site URL.
Confirm that Agent Barn can reach the site.
Save the credential again.
Validate it.
Restart the Agent.

Rotate the Jira token

Create a replacement token in Atlassian.
Record whether it is scoped or non-scoped.
Stop the Agent, or begin a restart-aware edit.
Open Keys & integrations.
Enter the complete replacement Jira credential.
Re-enter the site URL, authentication type, and email.
Apply and restart.
Validate the new token.
Test project and issue access.
Revoke the old token.

Stored credential values cannot be retrieved or partially edited.

Change the Jira account

Prepare an API token for the replacement Atlassian account.
Confirm its product and project permissions.
Replace the complete Jira credential in Agent Barn.
Apply and restart.
Validate the returned identity.
Test intended projects.
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

Stop the Agent, or begin a restart-aware edit.
Identify any assigned Skill requiring jira.
Remove or replace that Skill when permitted.
Open Keys & integrations.
Select Remove for Jira.
Apply the configuration.
Restart the Agent.
Confirm that Jira is unavailable.
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": "[email protected]",
        "api_token": "REDACTED"
      }
    }
  ]
}

Add a scoped Jira credential

{
  "secrets": [
    {
      "provider": "jira",
      "content": {
        "site_url": "https://example.atlassian.net",
        "use_scoped_token": true,
        "email": "[email protected]",
        "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 to configure an Atlassian credential for the intended Confluence spaces and page operations.