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

# Setup Jira API Parameters

> A concise walkthrough for configuring Jira API credentials and permissions, enabling secure interactions between bots/workflows and Jira.

## **Overview**

### **Purpose**

This guide details the steps required to configure API access for Jira. By following these instructions, you’ll enable your bots or workflows to securely create, update, and retrieve Jira issues, facilitating robust project tracking and automation.

<Note>
  This page covers **only** the Jira credential / connection setup. Save credentials in **Config -> Connections** — open **+ New Connection**, choose **Jira** under **Dev Tools**, and complete the **Connection** tab. See [Connections — Jira connections](/docs/Setup/Connections#jira-connections). Once the connection is saved you have two ways to use it:

  * To have Genesis **automatically pick up Jira tickets** when they are assigned, change status, or get an `@genesis` comment, continue to [Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation).
  * To use Jira **manually from agents** (create / update / search issues, transitions), see [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools).
</Note>

### Steps

<Steps>
  <Step title="Jira Access Verification">
    Confirm your Jira account and privileges.
  </Step>

  <Step title="API Token Generation">
    Create and securely store an API token for Cloud or Server/Data Center.
  </Step>

  <Step title="Permissions & Bot Access">
    Ensure proper permissions, network access, and readiness for automation.
  </Step>

  <Step title="Test & Troubleshoot">
    Verify configurations by creating, updating, or fetching Jira issues.
  </Step>
</Steps>

## **Step-by-Step Setup**

### **Step 1: Verify Jira Access**

1. **Jira Account**

   * Ensure you can log into your organization’s Jira instance.

2. **Administrative or Integration Permissions**

   * You may need admin privileges or specific permissions to create API tokens or configure integrations.

### **Step 2: Gather Jira Access Information**

You will need:

* **Jira Base URL**– Cloud Example: `https://<your-company>.atlassian.net`– Server/Data Center Example: `https://jira.<your-domain>.com`

* **Email Address**– Your Jira login email, tied to your Jira account.

* **API Token**– Serves as the “password” for API access, safer than using your actual password.

### **Step 3: Generate an API Token**

1. **For Jira Cloud**

   <Warning>
     **Important:** The token is displayed only once. Copy and store it securely.
   </Warning>

   * **Account Settings**: Log in → profile icon (top right) → “Account Settings” or “Manage Profile.”

   * **Security Settings**: Click on “API Tokens.”

   * **Create a New Token**: Provide a descriptive name (e.g., “Bot Integration”) → **copy** the token (shown once).

2. **For Jira Server/Data Center**

   * Generate a personal access token or coordinate with an admin for API integration details.

### **Step 4: Configure Access Permissions**

* **Sufficient Rights**

  * Ensure your Jira account can create, update, delete issues, and potentially manage projects.

* **API Integration**

  * Confirm with your admin that API integrations are enabled in your Jira instance.

* **Shared bot write identity (PAT / API token)**

  Genesis scopes Jira **write** actions (`CREATE_ISSUE`, `CREATE_CHILD_ISSUE`, `UPDATE_ISSUE`, `ADD_COMMENT`, `CREATE_LINK`, `ADD_ATTACHMENT`, and `TRANSITION_ISSUE`) by connection identity:

  * **User OAuth** connections act as the requesting user. The caller must be present in the active thread context.
  * **Personal** PAT or API-token connections allow writes only when the requesting user owns that connection.
  * **Shared** PAT or API-token connections fail closed for bot writes unless the connection is explicitly marked as a service or team identity, or Genesis uses the dedicated [Jira service worker](/docs/Setup/Jira-Automation#genesis-worker-parameter-reference) token for automation-managed threads.

  For shared bot writes, prefer a dedicated Atlassian **service account** (for example `Genesis`) with its own API token, and tell Genesis the token is not a person's by setting the connection's **Write identity** (locator field `identity_type`). The field is available on both the **API Token (Cloud)** and **Personal Access Token (Server/DC)** modes and defaults to **Human-owned token**, which keeps bot writes blocked.

  | `identity_type` value | Form label | Shared bot writes |
  | - | - | - |
  | `human` (default) | Human-owned token (bot writes blocked) | Blocked |
  | `service_account` | Service account (allows shared bot writes) | Allowed |
  | `team_owned` | Team-owned token (allows shared bot writes) | Allowed |

  Set it in either of two places:

  * **Connections page:** edit the shared Jira connection, pick **Service account** or **Team-owned token** under **Write identity**, and save.
  * **`connections_action` UPDATE:** include `identity_type` in `locator_json`. UPDATE **replaces** the stored locator rather than merging into it, so resend the full locator - `auth_type`, `host`, `email`, `token_scope_mode` and `identity_type` for Cloud, or `auth_type`, `host` and `identity_type` for Server/DC. The secret (`api_token` or `pat`) may be omitted to keep the stored value (connections saved through Genesis store it as a secret reference, which UPDATE preserves).

  ```json theme={null}
  {
    "auth_type": "api_token",
    "host": "https://yourcompany.atlassian.net",
    "email": "genesis@yourcompany.com",
    "token_scope_mode": "unscoped",
    "identity_type": "service_account"
  }
  ```

  Existing rows may still carry the older markers - `credential_owner_type` or `owner_type` set to `service`, `service_account`, `team` or `team_owned`, or a truthy (`true`, `1`, `yes`, `on`) `is_service_account`, `service_account` or `team_owned` flag. Genesis keeps honouring them, but they are not exposed in the Connections form and are not recommended for new connections; use `identity_type` instead. A recognised `identity_type` replaces the older string markers (`credential_owner_type` / `owner_type`), but the boolean flags are checked on their own: a row that still carries `team_owned: true` allows bot writes even with `identity_type: human`. When switching a connection back to a human-owned token, remove any such flag from the locator as well.

  Legacy `jira.shared` credentials from `EXT_SERVICE_CONFIG` follow the same shared PAT rule until migrated to a saved connection with a service-account or team-owned Write identity.

### **Step 5: Ensure Bot Access**

1. **Network Reachability**

   * Check that your bot or system can reach the Jira Base URL.

2. **Restricted Servers**

   * If behind a firewall, allow outbound connections to Jira.

### **Step 6: Start Using the Jira Tool**

* **Test Operations**

  * Try creating, updating, or fetching Jira issues to confirm proper setup.

* **Set Up Recurring Tasks**

  * Integrate automated tasks into broader workflows once confirmed.

<Note>
  Jira API-token connections in Genesis are PAT-class saved connections. The
  role saving or testing that connection needs `access_pat_connections_tools`;
  otherwise Genesis rejects the save or test request even if the Jira token
  itself is valid.
</Note>

<Note>
  Shared Jira automation and Jira service-worker setup are enabled by default.
  Operators can hide or disable those shared setup surfaces by setting
  `GENESIS_ENABLE_JIRA_AUTOMATION`,
  `GENESIS_JIRA_AUTOMATION_ENABLED`, or `ENABLE_JIRA_AUTOMATION`
  to a falsey value such as `false`, `0`, `no`, or `off`. Standard Jira saved
  connections and `jira_connector_tools` still work while the shared automation
  surfaces are disabled. Shared Jira automation setup requires
  `access_config_panel` or `manage_all_connections`.
</Note>

<Note>
  **Additional Tips**

  * Keep Credentials Secure: Avoid sharing or committing the api\_token publicly.

  * Troubleshooting: If issues arise, confirm user permissions, ensure API calls aren’t blocked, and verify a valid base\_url.
</Note>

## **Integration Relevance**

* **Project & Task Management**: The [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools) rely on these API parameters to create or modify issues.

* **Error Handling**: Combine with Slack or email notifications to inform teams about issue statuses.

* **Reporting & Analytics**: Pull Jira data for advanced metrics or dashboards once configurations are in place.

## **Configuration Details**

* **Token Security**: Store your token privately (e.g., environment variables, secure vault).

* **Permission Scopes**: Verify your account can perform all required tasks (issue creation, updates, etc.).

* **Token Expiration**: Some tokens might have expiration dates; keep track to avoid service interruptions.

## **Next Steps**

After the Jira connection is saved and tested:

1. **Configure automatic ticket pickup** — set up Genesis to start work on a ticket as soon as it is assigned, transitions to a tracked status, or receives an `@genesis` comment. Use a **shared** connection for automation. See [Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation).
2. **Use Jira manually from agents** — for ad-hoc create / update / search / transition operations, see [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools).

## **Related Pages**

* [Jira Automation (Auto-Pickup)](/docs/Setup/Jira-Automation)
* [Jira Connector Tools](/docs/Genbot-Toolkit/Jira-Connector-Tools)
* [Connections](/docs/Setup/Connections)