🌐 English · Русский

jira.js — Jira REST API client for Node.js, TypeScript & browsers

JavaScript / TypeScript library for Node.js and browsers to interact with Atlassian Jira APIs

About

Jira.js is a powerful, production-ready Node.js and browser-compatible TypeScript library that provides seamless interaction with Atlassian Jira Cloud APIs. This npm package offers comprehensive support for:

• Jira Cloud REST API v2/v3 - Complete platform API coverage
• Jira Agile Cloud API - Sprint, board, and backlog management
• Jira Service Desk Cloud API - Service desk operations

Key Features

• ✅ Type-Safe: Full TypeScript support with comprehensive type definitions and IntelliSense
• ✅ Promise-based: Clean, async/await-friendly API for every endpoint
• ✅ Tree-Shakable: Optimize bundle size by importing only what you need (perfect for browser apps)
• ✅ Universal: Works in Node.js (v20+) and modern browsers with full ESM/CJS support
• ✅ Complete Coverage: Nearly 100% of Jira Cloud REST API v2/v3, Agile, and Service Desk APIs
• ✅ Well Documented: Extensive JSDoc, API reference, and code examples
• ✅ Modern Stack: Built with TypeScript, supports ES Modules and CommonJS
• ✅ Actively Maintained: Regular updates with new Jira API features and bug fixes
• ✅ Production Ready: Used by thousands of developers in production environments

Perfect for building Jira integrations, automation tools, webhooks, CI/CD pipelines, custom Jira applications, and browser-based Jira management tools.

Table of Contents

• Getting Started
  • Installation
  • Quick Example
• Documentation
• Usage
  • Authentication
    • Email and API Token
    • OAuth 2.0
    • JWT (Atlassian Connect)
  • Error Handling
  • API Structure
• Tree Shaking
• Other Products
• License

Getting Started

Installation

Install the Jira.js npm package using your preferred package manager. Requires Node.js 20.0.0 or newer.

# Using npm
npm install jira.js

# Using yarn
yarn add jira.js

# Using pnpm
pnpm add jira.js

TypeScript users: Type definitions are included - no additional @types package needed!

Quick Example

Get started with Jira.js in under 5 minutes. This example shows how to create a Jira issue using the TypeScript client:

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your@email.com',
      apiToken: 'YOUR_API_TOKEN', // Create one: https://id.atlassian.com/manage-profile/security/api-tokens
    },
  },
});

async function createIssue() {
  const project = await client.projects.getProject({ projectIdOrKey: 'Your project id or key' });

  const newIssue = await client.issues.createIssue({
    fields: {
      summary: 'Hello Jira.js!',
      issuetype: { name: 'Task' },
      project: { key: project.key },
    },
  });

  console.log(`Issue created: ${newIssue.id}`);
}

createIssue();

Documentation

📚 Full API reference, guides, and examples available at: https://mrrefactoring.github.io/jira.js/

The documentation includes:

• Complete API reference for all endpoints
• TypeScript examples and code samples
• Authentication guides
• Error handling patterns
• Best practices and tips

Supported APIs

Jira.js provides comprehensive support for all major Jira Cloud APIs:

• Jira Platform REST API v2: Legacy API endpoints for projects, issues, users, and more
• Jira Platform REST API v3: Modern API with enhanced features and improved performance
• Jira Software (Agile) API: Sprint management, boards, backlogs, and agile workflows
• Jira Service Desk API: Service desk operations, customer management, and request handling

All APIs are fully typed with TypeScript definitions, making development faster and safer.

Usage

Authentication

Email and API Token

1. Create an API token: https://id.atlassian.com/manage-profile/security/api-tokens
2. Configure the client:

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: { email: 'YOUR@EMAIL.ORG', apiToken: 'YOUR_API_TOKEN' },
  },
});

OAuth 2.0

jira.js supports the full Atlassian OAuth 2.0 (3LO) flow. The simplest setup uses a static access token:

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    oauth2: { accessToken: 'YOUR_ACCESS_TOKEN' },
  },
});

Full flow with automatic refresh and cloudId resolution. Provide refresh credentials and the client refreshes the access token on expiry (and on 401), persists the rotated refresh token via onTokenRefresh, and routes requests through the API gateway (https://api.atlassian.com/ex/jira/{cloudId}) — so no host is needed. clientSecret and refresh are server-side only.

const client = new Version3Client({
  // no `host` — the cloudId is resolved automatically (pass `siteUrl` or `cloudId` to pin it)
  authentication: {
    oauth2: {
      accessToken: 'CURRENT_ACCESS_TOKEN',
      refreshToken: 'CURRENT_REFRESH_TOKEN',
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      expiresAt: Date.now() + 3600 * 1000, // optional; epoch milliseconds
      onTokenRefresh: async ({ accessToken, refreshToken, expiresAt }) => {
        await saveTokens({ accessToken, refreshToken, expiresAt }); // persist the rotated tokens
      },
    },
  },
});

jira.js also exports stateless helpers for the authorization-code flow — generateAuthorizationUrl, exchangeAuthorizationCode, refreshOAuth2Token, getAccessibleResources. See the step-by-step OAuth 2.0 guide.

JWT (Atlassian Connect)

For Atlassian Connect apps, authenticate with a per-request JWT signed using your app's shared secret. This is a server-side flow — the shared secret must never be shipped to a browser.

Note: Atlassian Connect is reaching end of support (Q4 2026), and new private apps can no longer be installed via a descriptor URL. JWT auth here is intended for existing Connect app installations.

• issuer: your app key — the key field in your atlassian-connect.json descriptor.
• secret: the sharedSecret your app receives in the body of the installed lifecycle webhook during the installation handshake. Store it per-tenant.
• expiryTimeSeconds (optional): token lifetime in seconds (defaults to 180, i.e. 3 minutes).

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    jwt: {
      issuer: 'YOUR_APP_KEY',
      secret: 'YOUR_SHARED_SECRET',
      expiryTimeSeconds: 180, // optional
    },
  },
});

A fresh JWT is generated for every request, with a query-string hash (qsh) bound to that request's method and URL. See the step-by-step setup guide for how to create a Connect app and obtain the issuer and secret.

Error Handling

Errors are categorized as:

• HttpException: Server responded with an error (includes parsed error details)
• AxiosError: Network/configuration issues (e.g., timeouts)

Example handling:

try {
  await client.issues.getIssue({ issueIdOrKey: 'INVALID-123' });
} catch (error) {
  if (error instanceof HttpException) {
    console.error('Server error:', error.message);
    console.debug('Response headers:', error.cause.response?.headers);
  } else if (error instanceof AxiosError) {
    console.error('Network error:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

API Structure

Access endpoints using the client.<group>.<method> pattern:

// Get all projects
const projects = await client.projects.searchProjects();

// Create a sprint
const sprint = await client.sprint.createSprint({ name: 'Q4 Sprint' });

Available API groups:

🔽 Agile Cloud API

• backlog
• board
• builds
• deployments
• developmentInformation
• devopsComponents
• epic
• featureFlags
• issue
• operations
• remoteLinks
• securityInformation
• sprint

🔽 Core REST API (v2/v3)

• api
• announcementBanner
• appDataPolicy
• applicationRoles
• appMigration
• auditRecords
• avatars
• classificationLevels
• dashboards
• filters
• fieldSchemes
• filterSharing
• groupAndUserPicker
• groups
• instanceInformation
• issues
• issueAttachments
• issueBulkOperations
• issueComments
• issueCustomFieldAssociations
• issueCustomFieldConfigurationApps
• issueCommentProperties
• issueFields
• issueFieldConfigurations
• issueCustomFieldContexts
• issueCustomFieldOptions
• issueCustomFieldOptionsApps
• issueCustomFieldValuesApps
• issueLinks
• issueLinkTypes
• issueNavigatorSettings
• issueNotificationSchemes
• issuePriorities
• issueProperties
• issueRedaction
• issueRemoteLinks
• issueResolutions
• issueSearch
• issueSecurityLevel
• issueSecuritySchemes
• issueTypes
• issueTypeSchemes
• issueTypeScreenSchemes
• issueTypeProperties
• issueVotes
• issueWatchers
• issueWorklogs
• issueWorklogProperties
• jiraExpressions
• jiraSettings
• jql
• jqlFunctionsApps
• labels
• licenseMetrics
• migrationOfConnectModulesToForge
• myself
• permissions
• permissionSchemes
• plans
• prioritySchemes
• projects
• projectTemplates
• projectAvatars
• projectCategories
• projectClassificationLevels
• projectComponents
• projectEmail
• projectFeatures
• projectKeyAndNameValidation
• projectPermissionSchemes
• projectProperties
• projectRoles
• projectRoleActors
• projectTypes
• projectVersions
• screens
• screenTabs
• screenTabFields
• screenSchemes
• serverInfo
• serviceRegistry
• status
• tasks
• teamsInPlan
• timeTracking
• uiModificationsApps
• users
• userNavProperties
• userProperties
• userSearch
• webhooks
• workflows
• workflowTransitionRules
• workflowSchemes
• workflowSchemeProjectAssociations
• workflowSchemeDrafts
• workflowStatuses
• workflowStatusCategories
• workflowTransitionProperties
• appProperties
• dynamicModules

🔽 Service Desk API

• customer
• info
• insight
• knowledgeBase
• organizations
• request
• requestType
• serviceDesk

See the full endpoint reference in the API documentation.

Tree Shaking & Bundle Optimization

Jira.js supports tree shaking to minimize your bundle size. Import only the modules you need:

// custom-client.ts
import { BaseClient } from 'jira.js';
import { Issues } from 'jira.js/version3';
import { Board } from 'jira.js/agile';

export class CustomClient extends BaseClient {
  issues = new Issues(this);
  board = new Board(this);
}

// Usage
const client = new CustomClient({ /* config */ });
await client.issues.getIssue({ issueIdOrKey: 'KEY-1' });

You can also import the typed parameter and model barrels via deep subpaths:

import type { SearchForIssuesUsingJqlEnhancedSearchPost } from 'jira.js/version3/parameters';
import type { Issue } from 'jira.js/version3/models';

// Equivalent via the root namespace (works with any TypeScript moduleResolution):
import { Version3 } from 'jira.js';
// type Params = Version3.Version3Parameters.SearchForIssuesUsingJqlEnhancedSearchPost;

The deep subpath form (jira.js/<api>/parameters, jira.js/<api>/models) requires an exports-aware resolver (moduleResolution: "bundler" | "node16" | "nodenext"). With the legacy moduleResolution: "node", use the root-namespace form above.

Benefits:

• Smaller bundle sizes for browser applications
• Faster load times
• Better performance in production

Use Cases

Jira.js is perfect for:

• 🔄 CI/CD Integration: Automate issue creation and updates in your deployment pipelines
• 🤖 Automation Scripts: Build custom automation for Jira workflows and processes
• 📊 Reporting & Analytics: Extract and analyze Jira data for custom dashboards
• 🔗 Webhook Handlers: Process Jira webhooks and integrate with external systems
• 🛠️ Custom Tools: Build admin tools, migration scripts, and custom Jira applications
• 📱 Browser Apps: Create browser-based Jira management interfaces
• 🔌 Third-Party Integrations: Connect Jira with other services and platforms

Common Questions (FAQ)

Q: Does this work with Jira Server/Data Center?
A: No, Jira.js is designed specifically for Jira Cloud. For on-premise Jira, consider using the REST API directly.

Q: Is TypeScript required?
A: No, but TypeScript is fully supported with comprehensive type definitions. You can use Jira.js with plain JavaScript too.

Q: Can I use this in the browser?
A: Yes! Jira.js works in both Node.js and modern browsers. Make sure to handle CORS if calling Jira APIs from a browser.

Q: How do I handle authentication?
A: Jira.js supports Basic Auth (email + API token), OAuth 2.0, and JWT for Atlassian Connect apps. See the Authentication section above.

Other Products

Explore our other Atlassian integration libraries:

• Confluence.js - Interact with Confluence API
• Trello.js - Trello API integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT License © MrRefactoring
See LICENSE for details.