README

Introduction

This package provides a simple and reliable HTTP Client to interact with the Jira Cloud REST API. The Client is generated from the official OpenAPI Specification of the Jira Cloud REST API and is designed for a seamless developer experience.

Jira Cloud vs Jira Software Cloud

The Jira Cloud REST API and Jira Software Cloud REST API are closely related, but they serve different scopes within the Atlassian ecosystem.

The Jira Cloud REST API is the core API, allowing you to interact with fundamental Jira features that are available in all Jira projects. Some key features include: managing users, projects, issues, custom fields, workflows, screens, and more.

The Jira Software Cloud REST API acts as an extension to the core API, allowing you to interact with software Jira features that are only available in Jira Software Projects. Some key features include: managing boards, sprints, backlogs, epics, and more.

Important

This package does not yet support the Jira Software Cloud REST API, and recommends lesstif/jira-cloud-restapi if you need these specific features. Note that lesstif/jira-cloud-restapi does not support the Jira Cloud REST API (only the Jira Software Cloud REST API), but you may use both that package and this one without conflicts.

Installation

Install this package using Composer:

composer require jira/client

Requirements

Version	PHP	Guzzle
1.x	8.3 - 8.4	7.x
2.x	8.1 - 8.4	None or 6.x - 7.x

When Guzzle is not installed, cURL is used instead.

Configuration

The Jira\Client\Client instance must be constructed with a Jira\Client\Configuration instance.

Authentication

a. Basic Authentication

use Jira\Client\Client;
use Jira\Client\Configuration;

$client = new Client(new Configuration(
    host: 'https://your-domain.atlassian.net',
    username: 'jira-username',
    password: 'jira-password',
));

Important

Basic Authentication using cookie-based authentication (e.g. your website password) was disabled by Atlassian on June 3rd, 2019, in accordance with their deprecation notice. Basic Authentication is still fully supported, but the password must be an API Token. As of December 13th, 2025, API Tokens are set to expire in one year. You will need to rotate your API Tokens prior to expiration.

Tip

Atlassian recommends only using Basic Auth for REST APIs for simple scripts, bots, and ad-hoc execution of the REST APIs. The expectation is that you will configure a single "admin/server" user account, and make calls to the API on behalf of this system-configured entity. If you intend to make calls to the API on behalf of an actual user, it is recommended that you use OAuth 2.0 (3LO) Apps instead.

b. OAuth 2.0 (3LO) App Authentication

use Jira\Client\Client;
use Jira\Client\Configuration;

$client = new Client(new Configuration(
    host: 'https://your-domain.atlassian.net',
    username: 'jira-username',
    accessToken: 'jira-token',
));

Tip

Atlassian recommends using OAuth 2.0 (3LO) Apps for apps created and managed in their developer console. The expectation is that you will be making API calls on behalf of an actual user. If you intend to make calls to the API on behalf of a system-configured admin-like entity, it is recommended that you use Basic Authentication instead.

Laravel

If you are using Laravel, you can bind the Configuration instance to the container in your AppServiceProvider:

use Illuminate\Support\ServiceProvider;
use Jira\Client\Configuration;

namespace App\Providers;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(Configuration::class, function () {
            return new Configuration(
                host: config('services.jira.host'),
                username: config('services.jira.username'),
                password: config('services.jira.password'),
            )
        });
    }
}

This example requires that you add entries to your services configuration file:

return [
    /* ... */

    'jira' => [
        'host' => env('JIRA_HOST', 'https://your-domain.atlassian.net'),
        'username' => env('JIRA_USERNAME', 'jira-username'),
        'password' => env('JIRA_PASSWORD')
    ],
];

Usage

This package strictly follows the OpenAPI Specification of the Jira Cloud REST API.

The API Specification for Operations includes an operationId, which determines the name of the methods available on the Client instance.

use Jira\Client\Schema;

$response = $client->createProject(new Schema\CreateProjectDetails(
    key: 'EX',
    name: 'Example',
    projectTypeKey: 'business',
    projectTemplateKey: 'com.atlassian.jira-core-project-templates:jira-core-project-management',
    description: 'Example description',
    avatarId: 10130,
    issueSecurityScheme: 1000,
    permissionScheme: 1000,
    notificationScheme: 1000,
    categoryId: 1000,
));

var_dump($response);

// object(ProjectIdentifiers)#1 (3) {
//   ["id"] => int(10042)
//   ["key"] => string(2) "EX"
//   ["self"] => string(43) "http://example.com/rest/api/2/project/10042"
// }

By following the OpenAPI specification, this package supports 100% of all operations documented by Atlassian.

Operations

Announcement Banner

App Data Policies

App Migration

App Properties

Application Roles

Audit Records

Get Audit Records

Avatars

Classification Levels

Get All Classification Levels

Dashboards

Dynamic Modules

Filter Sharing

Filters

Group And User Picker

Find Users And Groups

Groups

Issue Attachments

Issue Bulk Operations

Issue Comment Properties

Issue Comments

Issue Custom Field Associations

Issue Custom Field Configuration Apps

Issue Custom Field Contexts

Issue Custom Field Options

Issue Custom Field Options Apps

Issue Custom Field Values Apps

Issue Field Configurations

Issue Fields

Issue Link Types

Issue Links

Issue Navigator Settings

Issue Notification Schemes

Issue Priorities

Issue Properties

Issue Remote Links

Issue Resolutions

Issue Search

Issue Security Level

Issue Security Schemes

Issue Type Properties

Issue Type Schemes

Issue Type Screen Schemes

Issue Types

Issue Votes

Issue Watchers

Issue Worklog Properties

Issue Worklogs

Issues

JQL

JQL Functions Apps

Jira Expressions

Jira Settings

Labels

Get All Labels

License Metrics

Myself

Permission Schemes

Permissions

Plans

Priority Schemes

Project Avatars

Project Categories

Project Classification Levels

Project Components

Project Email

Project Features

Project Key And Name Validation

Project Permission Schemes

Project Properties

Project Role Actors

Project Roles

Project Templates

Create Custom Project

Project Types

Project Versions

Projects

Screen Schemes

Screen Tab Fields

Screen Tabs

Screens

Server Info

Get Jira Instance Info

Service Registry

Retrieve The Attributes Of Service Registries

Status

Tasks

Teams In Plan

Time Tracking

UI Modifications Apps

User Properties

User Search

Usernavproperties

Users

Webhooks

Workflow Scheme Drafts

Workflow Scheme Project Associations

Workflow Schemes

Workflow Status Categories

Workflow Statuses

Workflow Transition Properties

Workflow Transition Rules

Workflows

Schema

A

B

C

D

E

F

G

H

I

J

K

KeywordOperand

L

M

N

O

P

Q

QuickFilterPayload

jira / client

Maintainers

Details