Jira

Jira integration allows your product to connect with Atlassian Jira Cloud or Jira Server to fetch and manage issues, projects, users, and workflows. This integration is valuable for ticket synchronization, vulnerability tracking, DevSecOps workflows, and automated issue creation (e.g., linking vulnerabilities to Jira tickets).

Credentials Needed

To connect with Jira's REST API, you need API credentials depending on the deployment type:

For Jira Cloud:

• Jira Base URL (e.g., https://yourcompany.atlassian.net)
• Email Address (of Jira user)
• API Token (generated from Atlassian Account)

For Jira Server / Data Center:

• Jira Base URL (e.g., https://jira.yourcompany.com)
• Username
• Password or Personal Access Token (PAT)

Use API tokens instead of passwords wherever possible. Jira Cloud does not accept password-based Basic Auth; API tokens are mandatory.

Permissions Needed / API Scopes

Your Jira account must have sufficient permissions for the resources your integration needs.

Functionality	Required Permission	Description
View Projects	Browse Projects	Read all accessible projects
Read Issues	View Issues	Fetch existing issues
Create / Update Issues	Create Issues, Edit Issues	Create or modify issues
Manage Comments	Add Comments, Edit Comments	Add or update comments on issues
Manage Metadata	Administer Projects (optional)	Retrieve custom fields, components, etc.

Minimum Required Permissions for Read Access: Browse Projects, View Issues

For Create/Update Automation: Add Create Issues, Edit Issues, Add Comments

Creating Users / Access Tokens

For Jira Cloud (Atlassian Cloud)

1. Go to your Atlassian Account → https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API Token
3. Enter a label (e.g., IntegrationToken) and click Create
4. Copy the generated token
5. Store your credentials securely:
   • Email Address = your Atlassian login email
   • API Token = the generated token

For Jira Server / Data Center

1. Log in to Jira → Go to Profile → Personal Access Tokens (if supported)
2. Click Create Token, specify expiry and scopes
3. Copy the generated token
4. If PAT is not supported, use username + password for basic auth (less secure)

Test Connectivity

Using curl for Jira Cloud

curl -u <EMAIL>:<API_TOKEN> \
  -X GET \
  -H "Accept: application/json" \
  "https://yourcompany.atlassian.net/rest/api/3/project"

Example Response:

[
  {
    "id": "10000",
    "key": "SEC",
    "name": "Security Tickets",
    "projectTypeKey": "software"
  }
]

List Issues from a Project

curl -u <EMAIL>:<API_TOKEN> \
  -X GET \
  -H "Accept: application/json" \
  "https://yourcompany.atlassian.net/rest/api/3/search?jql=project=SEC&maxResults=5"

Example Response:

{
  "issues": [
    {
      "id": "10001",
      "key": "SEC-1",
      "fields": {
        "summary": "Cross-Site Scripting vulnerability",
        "status": {"name": "In Progress"},
        "assignee": {"displayName": "John Doe"}
      }
    }
  ]
}

Save the Results in the Platform and Create Connection

1. In your platform's integration module, securely store:
   • JIRA_BASE_URL
   • JIRA_EMAIL
   • JIRA_API_TOKEN (or password/PAT for Server)
2. Create a connection labeled Jira Integration
3. Test the connection by retrieving a list of projects
4. On success, you can enable optional workflows such as:
   • Auto-create issues from vulnerabilities
   • Sync issue statuses (e.g., Open → Resolved)
   • Add comments or tags automatically

Best Practices

• Always use API Tokens instead of passwords for Jira Cloud
• Store credentials securely in your encrypted vault or secret manager
• Assign integration users a dedicated Jira account with minimum required permissions
• Rotate API tokens periodically (every 90 days recommended)
• Implement rate limiting and caching — Jira API typically limits requests to 100 per 15 minutes per user (depending on plan)
• Log all API calls and failures for troubleshooting
• Handle HTTP 429 (Rate Limit) and 401 (Unauthorized) responses with retries and alerts
• Use project keys and issue types dynamically from /rest/api/3/issue/createmeta for automated ticket creation

Useful Jira API Endpoints

Resource	Method	Endpoint	Description
Get all projects	GET	/rest/api/3/project	List all accessible projects
Get issues (by JQL)	GET	/rest/api/3/search?jql=...	Search issues with custom filters
Get specific issue	GET	/rest/api/3/issue/{issueKey}	Retrieve issue details
Create issue	POST	/rest/api/3/issue	Create new issue
Add comment	POST	/rest/api/3/issue/{issueKey}/comment	Add comment to issue
Transition issue	POST	/rest/api/3/issue/{issueKey}/transitions	Update issue status
Get custom fields	GET	/rest/api/3/field	Retrieve available fields and IDs

Official Documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/

Example JSON Payload: Create Jira Issue

{
  "fields": {
    "project": { "key": "SEC" },
    "summary": "Critical SQL Injection vulnerability found",
    "description": "Details about the issue found in production API endpoint.",
    "issuetype": { "name": "Bug" },
    "priority": { "name": "High" }
  }
}

Request:

curl -u <EMAIL>:<API_TOKEN> \
  -X POST \
  -H "Content-Type: application/json" \
  -d @issue.json \
  "https://yourcompany.atlassian.net/rest/api/3/issue"

Response:

{
  "id": "10005",
  "key": "SEC-5",
  "self": "https://yourcompany.atlassian.net/rest/api/3/issue/SEC-5"
}