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

# Jira Credentials

Configure your Atlassian Jira API token to manage issues and project progress from your Jinba Flow workflows.

## Prerequisites

* An Atlassian account with access to a Jira Cloud site
* Permission to create API tokens (available to all Atlassian accounts)

## Creating a Jira API Token

<Warning>
  **Create a *personal* API token, not an *organization* API key.** These are two
  different things and only one works with Jira:

  * ✅ **Personal API token** — created at
    [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
    Can access Jira data.
  * ❌ **Organization API key** — created in the admin console
    (`admin.atlassian.com/o/<org>/api-keys`). These only carry org-admin scopes
    (`manage:org`, `*:admin`) and **cannot create or read Jira issues** — using
    one results in a `401 Unauthorized` no matter how many scopes you check.
</Warning>

1. Sign in to your Atlassian account at [id.atlassian.com](https://id.atlassian.com)
2. Navigate to **Security** → **API tokens**
3. Click **Create API token**
4. Enter a label (e.g. `Jinba Flow`) and click **Create**
5. Copy the generated token — it will only be shown once

Direct link: [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)

<Note>
  A **classic** token (prefix `ATATT…`) is recommended — it has full account
  access and needs no scope configuration. Scoped tokens (`ATCTT…`) also work and
  are auto-routed through the `api.atlassian.com` gateway, but you must grant the
  right scopes yourself. Keep `base_url` set to your site
  (`https://your-domain.atlassian.net`) either way.
</Note>

## Setting Up in Jinba Flow

1. Go to your workspace settings in Jinba Flow
2. Navigate to the **Secrets** section
3. Find **Jira** in the list and click **Add**
4. Enter your API token:
   * **API Token**: The token you copied from Atlassian
5. Click **Save**

## Configuring Your Jira Steps

Each Jira tool step requires the following config fields in addition to the secret:

| Field       | Description                   | Example                             |
| ----------- | ----------------------------- | ----------------------------------- |
| `base_url`  | Your Jira site URL            | `https://your-domain.atlassian.net` |
| `email`     | Your Atlassian account email  | `you@example.com`                   |
| `api_token` | Select your saved Jira secret | —                                   |

## Finding Your Jira Site URL

Your Jira Cloud base URL follows the pattern `https://<your-domain>.atlassian.net`. You can find it in the browser address bar when viewing your Jira board.

## Finding a User's Account ID

Jira identifies users by `accountId`, not by name or email. To find an account ID:

1. Open the user's Jira profile
2. The account ID appears in the URL: `.../jira/people/<accountId>`

Alternatively, use `JIRA_SEARCH_ISSUES` or the Jira user search API to look up account IDs programmatically.