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

# JIRA ITSM

> Instructions to authenticate with JIRA Cloud API using OAuth 2.0

## JIRA OAuth App

Leen uses OAuth 2.0 for secure authentication with JIRA. Leen's pre-configured OAuth app enables quick setup and handles the OAuth flow and token management automatically.

## Required Permissions

The JIRA OAuth app requires the following scopes:

| Scope                       | Purpose                                               |
| --------------------------- | ----------------------------------------------------- |
| `read:jira-work`            | Read JIRA projects, issues, comments, and attachments |
| `write:jira-work`           | Write access for passthrough endpoint operations      |
| `read:jira-user`            | Read user information and groups                      |
| `manage:jira-configuration` | Read users within groups                              |
| `manage:jira-webhook`       | Register and manage webhooks                          |
| `offline_access`            | Enable refresh tokens for long-lived access           |

## Onboarding

<Steps>
  <Step title="Create JIRA Connection">
    With your Leen API Key and your organization ID, make an API request to create a new JIRA connection.
    More information can be found on the [API Reference page.](/api-reference/provisioning/add-new-connection)

    <Accordion title="Example POST body and response">
      ```json theme={null}
      {
        "vendor": "JIRA"
      }
      ```

      The response will look like this:

      ```json theme={null}
      {
        "id": "c54de187-df62-4e95-b10f-0ab53b095d9d",
        "vendor": "JIRA",
        "refresh_interval_secs": 21600,
        "timeout_secs": 1800,
        "organization_id": "fbd8b095-3c39-4137-9478-c32308444202",
        "oauth2_authorize_url": "https://auth.atlassian.com/authorize?client_id=..."
      }
      ```
    </Accordion>

    <Accordion title="Example with connection options">
      You can optionally filter projects and provide custom mappings:

      ```json theme={null}
      {
        "vendor": "JIRA",
        "options": {
          "project_keys_filter": ["PROJ1", "ENG", "SEC"],
          "priority_mapping": [
            {
              "Highest": "CRITICAL"
            },
            {
              "High": "HIGH"
            },
            {
              "Medium": "MEDIUM"
            },
            {
              "Low": "LOW"
            },
            {
              "Lowest": "INFORMATIONAL"
            },
            {
              "Parked": "INFORMATIONAL"
            }
          ],
          "status_mapping": [
            {
              "To Do": "TODO"
            },
            {
              "In Progress": "IN_PROGRESS"
            },
            {
              "Done": "CLOSED"
            }
          ]
        }
      }
      ```
    </Accordion>
  </Step>

  <Step title="Authorize JIRA Access">
    Open the `oauth2_authorize_url` from the previous step in a browser.
    This will prompt you to authorize Leen to access your JIRA resources.

    1. Log in to your Atlassian account
    2. Select your JIRA site from the list
    3. Review the requested permissions
    4. Click **Accept** to grant access

           <img src="https://mintcdn.com/leen/6o3RxRkX4_tecN4s/images/jira/authorize.png?fit=max&auto=format&n=6o3RxRkX4_tecN4s&q=85&s=7791ae262f4b4f9b2f485c38d5c75475" alt="Jira-authorize" width="674" height="859" data-path="images/jira/authorize.png" />

    Once authorized, you will be redirected to Leen with a successful connection confirmation.

    <img src="https://mintcdn.com/leen/6o3RxRkX4_tecN4s/images/jira/successful_connection.png?fit=max&auto=format&n=6o3RxRkX4_tecN4s&q=85&s=a0a39b86d214d0a34a9d1991fbd3e563" alt="Jira-successful-connection" width="651" height="554" data-path="images/jira/successful_connection.png" />
  </Step>
</Steps>

## Connection Options

### Project Filter

You can optionally filter which JIRA projects to sync:

```json theme={null}
{
  "project_keys_filter": ["PROJ1", "PROJ2", "ENG"]
}
```

**Note:** If not specified, all accessible projects will be synced.

### Custom Priority Mapping

You can provide custom mappings from JIRA priorities to standardized ITSM priority values:

```json theme={null}
{
  "priority_mapping": [
    {
      "Highest": "CRITICAL"
    },
    {
      "High": "HIGH"
    },
    {
      "Medium": "MEDIUM"
    },
    {
      "Low": "LOW"
    },
    {
      "Lowest": "INFORMATIONAL"
    },
    {
      "Parked": "INFORMATIONAL"
    }
  ],
}
```

**Valid ITSM Priority Values:**

* `CRITICAL` - Highest priority, blockers, emergencies
* `HIGH` - High priority, major issues
* `MEDIUM` - Medium or normal priority
* `LOW` - Low priority, minor issues
* `INFORMATIONAL` - Lowest priority
* `UNKNOWN` - Unmapped priorities

If not provided, Leen will auto-generate mappings based on priority names and keywords.

### Custom Status Mapping

You can provide custom mappings from JIRA statuses to standardized ITSM status values:

```json theme={null}
{
  "status_mapping": [
    {
      "To Do": "TODO"
    },
    {
      "In Progress": "IN_PROGRESS"
    },
    {
      "Done": "CLOSED"
    }
  ]
}
```

**Valid ITSM Status Values:**

* `OPEN` - Newly opened
* `TODO` - In backlog
* `IN_PROGRESS` - Actively being worked on
* `IN_REVIEW` - Under review
* `BLOCKED` - Blocked or on hold
* `PENDING` - Pending validation or testing
* `RESOLVED` - Resolved, awaiting closure
* `CLOSED` - Completed and closed
* `CANCELLED` - Cancelled or rejected
* `UNKNOWN` - Unmapped statuses

If not provided, Leen will auto-generate mappings based on status names, keywords, and JIRA status categories.

**The JIRA integration also supports near real-time updates for tickets using webhooks, Please refer to the setup
instructions [here](/webhooks/integrations/jira-webhooks).**