Setup Jira API Parameters

​

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.

​

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
   Important: The token is displayed only once. Copy and store it securely.
   • 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 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).
  {
    "auth_type": "api_token",
    "host": "https://yourcompany.atlassian.net",
    "email": "[email protected]",
    "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.

​

Integration Relevance

• Project & Task Management: The 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).
2. Use Jira manually from agents — for ad-hoc create / update / search / transition operations, see Jira Connector Tools.

​

Related Pages

• Jira Automation (Auto-Pickup)
• Jira Connector Tools
• Connections