Jira Integration Guide

Overview

Integrating your application with Jira enables seamless issue tracking, project management, and workflow automation directly from your platform. This guide walks you through everything you need to get started.

Prerequisites

• Jira Cloud or Jira Server with admin access.
• API token (for Cloud) or a dedicated service account (for Server).
• HTTPS endpoint for receiving webhooks.
• OAuth 2.0 credentials if you prefer OAuth authentication.

Setup

1. Create an API token (Jira Cloud)

1. Log in to Atlassian API Tokens.
2. Click Create API token, give it a name, and copy the generated token.

2. Configure a new Application Link (Jira Server)

Administration → Applications → Application Links → Create new link

3. Install the Integration Package

npm install @yourorg/jira-integration

Authentication

Two methods are supported:

Basic Auth (API Token)

const auth = Buffer.from(`email@example.com:${process.env.JIRA_API_TOKEN}`).toString('base64');
axios.get('https://your-domain.atlassian.net/rest/api/3/issue/KEY-1', {
    headers: { Authorization: `Basic ${auth}` }
});

OAuth 2.0

Follow the OAuth flow to obtain an access token. Use the token in the Authorization: Bearer <token> header.

Webhooks

Set up webhooks to receive real‑time updates from Jira.

Create a Webhook

POST https://your-domain.atlassian.net/rest/webhooks/1.0/webhook
{
  "name": "My Integration Hook",
  "url": "https://yourapp.com/api/jira/webhook",
  "events": ["jira:issue_created","jira:issue_updated"]
}

Handle Incoming Payloads

app.post('/api/jira/webhook', (req, res) => {
  const { webhookEvent, issue } = req.body;
  // process event
  res.sendStatus(204);
});

FAQs

Can I use the same token for multiple projects?

Yes, a single API token can access all projects the token owner has permission to view.

What rate limits apply?

Jira Cloud enforces 500 requests per 10 seconds per user. Use pagination and exponential back‑off.

How do I troubleshoot webhook delivery failures?

Check the Webhook delivery logs in Jira administration and ensure your endpoint returns a 2xx status code.