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

# Let AI Agents Create and Triage Jira Issues

> Let agents search Jira with JQL, create and update issues, comment, and move tickets through workflows. Connect in one click with Atlassian OAuth.

## Overview

Buckle connects AI agents to Jira Cloud. Agents can search issues with JQL, read and create them, comment, and move them through a workflow. The gateway injects the token into requests to `api.atlassian.com`, so your agent never sees it.

Connecting takes one click. You don't create an Atlassian app or copy any keys.

## What you will set up

* A Jira Cloud connection through Atlassian OAuth, with no app or keys to create
* Automatic token injection on requests to `api.atlassian.com`
* Per-agent, per-tool access, such as approval before deleting issues

## Connect Jira

**1. Click Connect**

In the Buckle dashboard, open **Settings** > **Apps** > **Jira** and click **Connect Jira**.

![Buckle connect window for Jira, showing the Connect to Jira button and an auto-connect countdown.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/jira/buckle-connect-jira.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=dba36145d981728d6e130c96ae5d10c3)

The Jira connect window in Buckle.

**2. Accept in Atlassian**

Sign in to Atlassian, pick your Jira site, and click **Accept**. You're done. Buckle keeps the connection active from then on.

> [!NOTE]
>
> You don't need to be a Jira admin. Atlassian may show a notice that the app hasn't been reviewed by Atlassian yet. It's safe to continue.

## What agents can do

| Tool | Description |
| - | - |
| **Search issues** | Find issues with JQL |
| **Get issue** | Read an issue and its sub-resources |
| **List projects** / **Get project** | List projects in the site, or read one |
| **Create issue** / **Update issue** | Open a new issue, or change its fields |
| **Add comment** | Comment on an issue |
| **Transition issue** | Move an issue through its workflow |
| **Assign issue** | Assign an issue to a user |
| **Delete issue** | Delete an issue |

## Controlling access

[Grant](/docs/guides/agent-access.md) the connection to each agent that needs it, and choose per tool what runs freely, what needs approval, and what's blocked. For example, let an agent search and read freely, but put **Transition issue** and **Delete issue** behind approval. Organization [rules](/docs/guides/rules.md) add guardrails on top. A blocked request never reaches Jira.

To disconnect, remove the connection in **Settings** > **Apps** > **Jira**, then revoke Buckle in Atlassian under **Account settings** > **Connected apps**.

***

## Self-hosted: use your own Atlassian app

> [!NOTE]
>
> **Skip this section on Buckle Cloud.** It's only for self-hosted Buckle without `ATLASSIAN_CLIENT_ID` and `ATLASSIAN_CLIENT_SECRET` set, or if you want your own company name on Atlassian's consent screen. One Atlassian app serves both Jira and Confluence: you save it once, register one callback URL, and people connect either app with it.

> [accordion] 1. Create the Atlassian app
>
> Go to [developer.atlassian.com/console/myapps](https://developer.atlassian.com/console/myapps/). Select **Create** > **OAuth 2.0 integration**, name it `Buckle`, accept the terms, and select **Create**. For **Access type**, choose **Resource-level**, so the token only reaches the site you pick.

> [accordion] 2. Add the permissions
>
> Open **Permissions**. For each API, click **Add**, then **Configure**:
>
> | API | Scopes |
> | - | - |
> | **Jira API** | `read:jira-work`, `write:jira-work`, `read:jira-user` |
> | **User identity API** | `read:me` |
>
> Use these exact classic scope names. The granular ones (`read:issue:jira` and so on) don't match what Buckle requests.
>
> > [!WARNING]
> >
> > Also add the Confluence scopes from the [Confluence page](/docs/integrations/confluence.md#self-hosted-use-your-own-atlassian-app), even if you only use Jira. Atlassian keeps one consent per person for each app, so Buckle asks for the Jira and Confluence scopes together. If any of them is missing from the app, Atlassian shows an error instead of the consent screen.
>
> ![Atlassian developer console Permissions page showing Scopes Used 4, with the Jira API row at 3 scopes and the User identity API row at 1 scope.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/jira/02-permissions.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=54e944b0c6a28c2c389d3384f93cd2ca)
>
> Permissions after adding all four scopes.

> [accordion] 3. Add the callback URL
>
> In Buckle, open **Settings** > **Apps** > **Jira** > **Custom credentials** and copy the **Redirect URI**. It ends in `/v1/apps/oauth/atlassian/callback`, the same URI for Jira and Confluence. In the developer console, open **Authorization**, click **Configure** next to OAuth 2.0 (3LO), paste it into **Callback URLs**, and save.
>
> ![Buckle Custom credentials card for Jira with the setup guide link, the Redirect URI and its copy button, and the client ID and secret fields.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/jira/buckle-custom-credentials-jira.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=9608539ea16eeeaf094b82d18199d167)
>
> Copy the Redirect URI from Custom credentials in Buckle.

> [accordion] 4. Connect with your app
>
> In the developer console, open **Settings** and copy the **Client ID** and **Secret** under **Authentication details**.
>
> ![Atlassian developer console Settings page showing the Authentication details card with a Client ID field and a masked Secret field, each with a copy button.](https://mintcdn.com/onecli-17d3f772/h1DTAVlDkLshz4JZ/images/integrations/jira/04-settings-credentials.png?fit=max\&auto=format\&n=h1DTAVlDkLshz4JZ\&q=85\&s=a7e7762893e8bd52adf9ffc1e9e43841)
>
> Client ID and Secret on the Settings page.
>
> Paste both into **Settings** > **Apps** > **Jira** > **Custom credentials**, select **Save credentials**, then **Connect** and accept in Atlassian. The app now serves Confluence too: connect it from **Settings** > **Apps** > **Confluence** without entering credentials again.
>
> > [!NOTE]
> >
> > An Atlassian app has only one callback URL. If your app still has an older per-app URI (ending in `/v1/apps/jira/callback`), replace it with the one above.

## FAQ

> [accordion] Do I need to be a Jira admin to connect?
>
> No. Any Jira user can connect. Atlassian may show a notice that the app hasn't been reviewed yet, and it's safe to continue.

> [accordion] Does the agent see my Atlassian token?
>
> No. The token stays in Buckle, and the gateway adds it at the proxy. See [How it works](/docs/how-it-works.md).

> [accordion] Can I stop agents from deleting issues?
>
> Yes. Block **Delete issue** or put it behind approval when you [grant](/docs/guides/agent-access.md) the connection.

> [accordion] Does one Atlassian connection cover Confluence too?
>
> On self-hosted, one Atlassian app serves both Jira and [Confluence](/docs/integrations/confluence.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.