JIRA ITSM

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.

User Creation

JIRA Cloud users are managed through Atlassian Administration:

Atlassian Admin Hub

Go to https://admin.atlassian.com
Navigate to Directory > Users
Click Invite users
Enter the user’s email address
Assign to the appropriate JIRA site

JIRA Site Administration (Site Admins)

Go to your JIRA site (e.g., yourcompany.atlassian.net)
Click Settings (gear icon) > User management
Click Invite users
Enter email and select access level

Required Permissions

The user authorizing the Jira connection must have the Administer Jira global permission.

Administer Jira Global Permission

This permission is required because the OAuth scopes include:

manage:jira-configuration - Requires “Administer Jira” global permission to manage Jira global settings
manage:jira-webhook - Requires “Administer Jira” global permission to manage webhooks
read:jira-user - Requires permission to view user profiles and group information

Important: OAuth scopes alone do not grant access. The authorizing user must have the corresponding Jira permissions. For example, if a user does not have the “Administer Jira” permission, operations won’t succeed even if the app has the required scopes.

How to Grant Administer Jira Permission

In most Jira Cloud instances, the jira-administrators or org-admins group already has the “Administer Jira” permission granted by default, so you may only need to add your user to that group.

To grant the Administer Jira permission, you need to add the org-admins group to the global permission:

Go to your JIRA site
Click the Settings icon (⚙️) in the top right
Select System from the menu
Click Global Permissions
Scroll to the bottom to find the Add Permission section
In the Permission dropdown, select Administer Jira
In the Group field, select or enter org-admin
Click Add

Then add users to the org-admins group:

In Jira settings, navigate to User management > Groups
Find the org-admins group
Click on the group and add the authorizing user

Note: You must be an existing Jira admin or Site admin to access the Global Permissions page. Being a Site Admin at the Atlassian account level does not automatically grant Jira-specific admin permissions.

Key Points

The authorizing user must be in the org-admins group
The user selects which JIRA site to connect during authorization

Recommendation: Ensure the authorizing user is either an Organization Admin or Site Admin who has been added to the org-admins group to guarantee access to all necessary JIRA resources including webhooks and configuration data.

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

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.

Example POST body and response

{
  "vendor": "JIRA"
}

The response will look like this:

{
  "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=..."
}

Example with connection options

You can optionally filter projects and provide custom mappings:

{
  "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"
      }
    ]
  }
}

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.

Log in to your Atlassian account
Select your JIRA site from the list
Review the requested permissions
Click Accept to grant access

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

Connection Options

Project Filter

You can optionally filter which JIRA projects to sync:

{
  "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:

{
  "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:

{
  "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.

Get Started

Integrations

OnRamp

Webhooks

JIRA OAuth App

User Creation

Required Permissions

Administer Jira Global Permission

How to Grant Administer Jira Permission

Key Points

Required Permissions

Onboarding

Connection Options

Project Filter

Custom Priority Mapping

Custom Status Mapping

​JIRA OAuth App

​User Creation

​Required Permissions

​Administer Jira Global Permission

​How to Grant Administer Jira Permission

​Key Points

​Required Permissions

​Onboarding

​Connection Options

​Project Filter

​Custom Priority Mapping

​Custom Status Mapping

JIRA OAuth App

User Creation

Required Permissions

Administer Jira Global Permission

How to Grant Administer Jira Permission

Key Points

Required Permissions

Onboarding

Connection Options

Project Filter

Custom Priority Mapping

Custom Status Mapping