---
title: "Jira APIの使い方｜Cloud REST API v3の認証とJQL検索・課題作成・Webhookの実装例"
url: "https://www.issoh.co.jp/tech/details/20077/"
published: 2026-11-22
updated: 2026-11-22
categories: ["業務システム"]
publisher: "株式会社一創"
---

# Jira APIの使い方｜Cloud REST API v3の認証とJQL検索・課題作成・Webhookの実装例

Jira APIは、Jiraの課題やプロジェクト、ワークフローをHTTPのREST呼び出しで操作するための公開APIです。社内システムで起きた障害を自動で課題として起票する、JQLで抽出した課題を集計して週次レポートにする、課題のステータス変更をWebhookで受けて別システムへ反映するといった連携に使います。この記事では、Jira Cloudの現行版であるREST API v3を対象に、認証方式の選び方、旧エンドポイントから移行したJQL検索、ADF形式での課題作成、Webhookの受信、レート制限への備えまでを、2026年11月時点の公式ドキュメントに沿ってコード付きで説明します。

## まとめ：Jira Cloud REST APIで連携を組む前に決める認証・検索・通知の要点

- **認証**：社内のスクリプトならメールアドレスとAPIトークンのBasic認証で始められる。権限を絞るならスコープ付きトークンを使い、呼び出し先を`api.atlassian.com`に変える。
- **トークンの期限**：APIトークンの有効期限は1〜365日。期限切れで夜間バッチが止まる前提で、更新の担当と手順を決めておく。
- **検索**：旧`/rest/api/3/search`は削除が進んでいる。新規実装は`/rest/api/3/search/jql`を使い、`nextPageToken`でページを送る。
- **課題作成**：v3では説明欄（description）にAtlassian Document Format（ADF）のJSONを渡す。プレーンな文字列を入れると400になる。
- **ステータス変更**：statusフィールドの書き換えではなく、トランジションAPIでワークフローを進める。
- **Webhook**：最大5回の再送と重複配信がある。署名の検証と配信IDでの重複排除を受信側に組み込む。

## Jira Cloud REST API v3の全体像とv2・Data Center版の違い

Jira CloudのREST APIには、v2とv3の2つの版が並んで公開されています。どちらも`https://<サイト名>.atlassian.net/rest/api/<版>/`の下にリソースが並ぶ構成で、新しく書くコードはv3を前提にします。

### v3とv2の差はADF対応、連携で使う主なエンドポイントの対応表

[Jira Cloud REST API v3の概要ページ](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/)では、v3の特徴として説明欄やコメントなどのリッチテキストをADFで扱える点が挙げられています。v2での受け取り形式はウィキ記法の文字列です。それ以外のエンドポイント体系はほぼ共通なので、既存のv2のコードをv3に移すときは、リッチテキストを扱う箇所だけを書き換えれば足ります。

| やりたいこと      | メソッドとパス                  | 補足                  |
| ----------- | ------------------------ | ------------------- |
| 疎通と本人確認     | GET /myself              | 認証が通ったユーザーを返す       |
| JQLで課題を検索   | GET・POST /search/jql     | nextPageTokenでページ送り |
| 件数だけ数える     | POST …/approximate-count | 概算の件数を返す            |
| 課題を作成       | POST /issue              | descriptionはADF     |
| 作成に要る項目を調べる | GET /issue/createmeta/…  | 課題タイプとフィールドの一覧      |
| ステータスを進める   | GET・POST …/transitions   | 遷移IDを指定             |
| コメントを追加     | POST /issue/…/comment    | 本文はADF              |

表のパスは`/rest/api/3`より後ろの部分です。連携の初版では、表の上から順に「疎通→検索→作成→遷移」の4つが動けば業務の大半をまかなえます。

### Data Center版とCloud版でURL・認証・廃止済みAPIが異なる点の確認

検索で見つかる日本語の解説には、自社サーバーで動かすData Center版の記事が混ざっています。Data Center版のAPIは`/rest/api/2/`が中心で、認証にはパーソナルアクセストークンを使います。Cloud版で使うメールアドレスとAPIトークンの組み合わせとは別物です。

Cloud版では、旧検索APIの削除と、引数なしのcreatemetaの非推奨化が進みました。手元のサンプルコードが`startAt`でページを送っていたり、`/rest/api/3/issue/createmeta`を引数なしで呼んでいたりしたら、古い仕様のコードだと判断して書き換えます。Atlassianの別製品ですが、同じ時期に版の移行があったConfluenceの事情は[Confluence REST APIのv1とv2の違いと移行手順](https://www.issoh.co.jp/tech/details/17390/)でまとめています。

## 認証方式を選ぶ：APIトークン・スコープ付きトークン・OAuth 2.0の使い分け

Jira Cloudで使える認証は、大きく分けてAPIトークンのBasic認証、スコープ付きAPIトークン、OAuth 2.0（3LO）の3つです。誰の権限で、どこまでの操作を許すかで選びます。

### メールアドレスとAPIトークンのBasic認証でmyselfを呼ぶ疎通確認

[Jira CloudのBasic認証のページ](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/)によると、パスワードによる認証は廃止済みで、代わりに「メールアドレス:APIトークン」をBase64にした値をAuthorizationヘッダーに入れます。まずはcurlで、認証が通るかを確かめます。

```
# 環境変数に接続情報を入れておく（トークンをコードに直書きしない）
export JIRA_SITE="https://your-site.atlassian.net"
export JIRA_EMAIL="bot@example.com"
export JIRA_TOKEN="発行したAPIトークン"

# 認証が通ると、トークンの持ち主のaccountIdと表示名が返る
curl -s -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -H "Accept: application/json" \
  "$JIRA_SITE/rest/api/3/myself"
```

401が返るときは、メールアドレスの誤りかトークンの失効を疑います。[REST APIの仕組みとステータスコード](https://www.issoh.co.jp/tech/details/13588/)の基礎があると切り分けが速くなります。ログインに続けて失敗した場合は、CAPTCHAが有効になり、APIでの認証ができなくなる点にも注意が必要です。

連携専用のJiraユーザーを1人用意し、そのユーザーでトークンを発行する構成をおすすめします。担当者個人のトークンで動かすと、退職や異動でアカウントが止まった日に連携も止まります。

### スコープ付きAPIトークンはapi.atlassian.com経由で最長365日

[AtlassianアカウントのAPIトークン管理のページ](https://support.atlassian.com/ja/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)では、トークンの有効期限は1日から365日の範囲で選ぶと説明されています。2024年12月15日以降に作ったトークンは既定で1年後に失効し、それより前に作ったトークンも2026年3月14日から5月12日の間に失効する扱いになりました。

同じページは、作成時に製品とスコープを選べる「スコープ付きトークン」を、より安全な方式として推奨しています。スコープ付きトークンでJiraを呼ぶ場合、接続先は`https://<サイト名>.atlassian.net`ではなく`https://api.atlassian.com/ex/jira/{cloudId}`に変わります。

### 社外の利用者に使わせる連携はOAuth 2.0の3LOでcloudIdを取得

自社のサービスから顧客のJiraに接続するような、利用者ごとに認可を得る連携ではOAuth 2.0（3LO）を使います。[OAuth 2.0（3LO）アプリのページ](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/)の手順は次のとおりです。

1. 開発者コンソールでアプリを作り、必要なスコープとコールバックURLを登録する
2. 利用者を`https://auth.atlassian.com/authorize`へ誘導し、`audience=api.atlassian.com`と`prompt=consent`を付けて同意を得る
3. 返ってきた認可コードを`https://auth.atlassian.com/oauth/token`でアクセストークンに交換する
4. `https://api.atlassian.com/oauth/token/accessible-resources`でサイトの一覧を取り、各サイトの`id`をcloudIdとして控える
5. `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/...`へBearerトークン付きで要求する

長期間動かす連携では、認可URLのscopeに`offline_access`を足してリフレッシュトークンを受け取ります。リフレッシュトークンは使うたびに新しいものに置き換わる方式で、90日使わないことが失効の条件です。古いトークンを上書き保存し損ねる実装の誤りが多いため、トークン更新の処理は1か所にまとめます。

## JQL検索を実装する：search/jqlとnextPageTokenで全件を取得する手順

課題の一覧取得は`POST /rest/api/3/search/jql`で行います。次のPythonのコードは、JQLに合う課題を最後のページまで取り切り、キー・要約・ステータスを返す例です。ライブラリは`requests`だけを使います。

```
import os
import requests

SITE = os.environ["JIRA_SITE"]  # 例: https://your-site.atlassian.net
AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_TOKEN"])

def search_issues(jql, fields=("summary", "status", "assignee")):
    """JQLに一致する課題をnextPageTokenで最後まで取得する"""
    url = f"{SITE}/rest/api/3/search/jql"
    body = {"jql": jql, "fields": list(fields), "maxResults": 100}
    issues = []
    while True:
        res = requests.post(url, json=body, auth=AUTH, timeout=30)
        res.raise_for_status()
        data = res.json()
        issues.extend(data.get("issues", []))
        token = data.get("nextPageToken")
        if not token:  # 最後のページにはnextPageTokenが含まれない
            break
        body["nextPageToken"] = token
    return issues

if __name__ == "__main__":
    jql = 'project = OPS AND status != Done AND updated >= -7d ORDER BY updated DESC'
    for issue in search_issues(jql):
        f = issue["fields"]
        print(issue["key"], f["status"]["name"], f["summary"])
```

JQLは画面の課題検索と同じ構文です。

### 旧searchからの移行で変わるstartAt廃止と件数取得の方法

[課題検索のリファレンス](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/)では、旧`/rest/api/3/search`は「Currently being removed」と表示され、後継として`/rest/api/3/search/jql`が載っています。[AtlassianのナレッジベースのJQL検索の記事](https://confluence.atlassian.com/jirakb/run-jql-search-query-using-jira-cloud-rest-api-1289424308.html)も、新しいエンドポイントへの移行を案内しています。移行で変わる点は次の4つです。

| 項目      | 旧 /search     | 新 /search/jql           |
| ------- | ------------- | ----------------------- |
| ページ送り   | startAtで位置を指定 | nextPageTokenを次の要求に渡す   |
| 総件数     | totalで返る      | 返らない（別APIで数える）          |
| JQLの条件  | 条件なしでも検索できた   | 検索条件のある「bounded」なJQLが必須 |
| 既定の取得項目 | 多くのフィールドを返した  | fieldsで欲しい項目を指定する       |

リファレンスによると、`maxResults`の既定は50件です。取得する項目が多いと1ページの件数は自動で減り、IDやキーだけを指定したときに1ページの件数が最も多くなります。`order by key desc`のような条件の無いJQLは受け付けられないため、`project = OPS`や`updated >= -30d`といった絞り込みを必ず入れます。

画面に「全○件」と出したい場合は、`POST /rest/api/3/search/approximate-count`に同じJQLを送って件数を得ます。

## 課題を作成・更新する：ADF形式の説明文とトランジションの実行例

課題の作成は`POST /rest/api/3/issue`です。[課題のリファレンス](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/)には、description・environment・複数行テキストのカスタムフィールドはADFで渡し、1行テキストのカスタムフィールドは文字列で渡すと書かれています。ADFは段落や見出しをJSONの入れ子で表す形式で、[ADFの構造のページ](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/)に要素の一覧があります。

```
curl -s -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  "$JIRA_SITE/rest/api/3/issue" \
  -d '{
    "fields": {
      "project":   { "key": "OPS" },
      "issuetype": { "name": "Task" },
      "summary":   "受注連携バッチがタイムアウトで停止",
      "labels":    ["auto-created"],
      "description": {
        "type": "doc",
        "version": 1,
        "content": [
          { "type": "paragraph",
            "content": [ { "type": "text", "text": "02:15 の実行で外部APIが30秒以内に応答しませんでした。" } ] }
        ]
      }
    }
  }'
# 成功すると201と、作成された課題のid・key・selfが返る
```

監視システムから自動で起票する場合は、同じ障害で課題が何十件もできないよう、起票前にJQLで「同じラベルが付いた未完了の課題」を検索し、あればコメント追加に切り替えます。

### 必須フィールドとカスタムフィールドIDをcreatemetaで調べる手順

プロジェクトごとに必須項目は異なり、足りないと400が返って`errors`に項目名が並びます。必要な項目は`GET /rest/api/3/issue/createmeta/{プロジェクトキー}/issuetypes`で課題タイプの一覧を取り、続けて`/issuetypes/{課題タイプID}`でその課題タイプのフィールドを取ると分かります。

カスタムフィールドは画面上の名前ではなく、`customfield_10016`のようなIDで指定します。設定ファイルに「業務上の名前→フィールドID」の対応表を持たせ、環境ごとに切り替えると移行の事故を防げます。

### ステータス変更はstatusの書き換えではなくtransitionsで行う

課題のステータスは、編集APIでstatusフィールドを書き換えても変わりません。`GET /rest/api/3/issue/{課題キー}/transitions`でその課題が今たどれる遷移の一覧を取り、目的の遷移の`id`を`POST`で送ります。

```
# いま実行できる遷移の一覧（idとnameを確認する）
curl -s -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  "$JIRA_SITE/rest/api/3/issue/OPS-123/transitions"

# idが31の遷移（例: 完了）を実行する。成功時は204で本文なし
curl -s -u "$JIRA_EMAIL:$JIRA_TOKEN" \
  -X POST -H "Content-Type: application/json" \
  "$JIRA_SITE/rest/api/3/issue/OPS-123/transitions" \
  -d '{ "transition": { "id": "31" } }'
```

遷移のIDはワークフローごとに決まり、管理者がワークフローを変えると番号が変わることがあります。IDを固定値で埋め込まず、遷移の`name`から実行時にIDを引く実装にしておくと、ワークフローの変更に対応しやすい実装です。ワークフローやボードの設計そのものは[Jiraの使い方｜スペース作成・エピックの使い分け](https://www.issoh.co.jp/tech/details/7859/)で扱っています。

## Webhookで課題の変化を受け取る：登録方法・署名検証・再送への備え

課題の変化を外部システムへ即時に伝えるなら、定期検索ではなくWebhookを使います。[Jira CloudのWebhookのページ](https://developer.atlassian.com/cloud/jira/platform/webhooks/)に、登録の経路と配信の仕様がまとまっています。

### 管理画面・REST・アプリの動的登録の違いと30日の有効期限

社内の連携で使うのは、Jiraの管理画面から登録する方法か、管理者権限で`/rest/webhooks/1.0/webhook`に登録する方法です。ConnectアプリやOAuth 2.0アプリは`/rest/api/3/webhook`で動的に登録します。

| 登録経路              | 向いている用途               | 注意点               |
| ----------------- | --------------------- | ----------------- |
| 管理画面              | 社内システム1つへの通知          | JQLで対象プロジェクトを絞れる  |
| webhooks 1.0のREST | 構成をコードで管理したい社内連携      | Connectアプリは使えない   |
| v3の動的登録           | OAuth 2.0・Connectのアプリ | 30日で期限切れ。PUTで延長する |

動的Webhookは作成または更新から30日で期限が切れ、OAuth 2.0アプリはユーザー・サイトごとに5件までしか登録できません。JQLのフィルターで使える項目はproject・issuetype・statusなどに限られ、演算子も`=`・`!=`・`IN`・`NOT IN`だけです。

### X-Hub-Signatureの検証と最大5回の再送に備えた重複排除

Webhookにシークレットを設定すると、本文のHMAC署名が`X-Hub-Signature`ヘッダーに`sha256=署名`の形で付きます。配信に失敗したとき、Jiraは408・409・425・429・5xxの応答や接続失敗を対象に、5〜15分の間隔をあけて最大5回まで再送します。同じイベントが2回届くことがあるため、`X-Atlassian-Webhook-Identifier`で重複した配信を除外する手順が必要です。

```
import hashlib
import hmac
import os
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["JIRA_WEBHOOK_SECRET"].encode()
seen_ids = set()  # 本番ではRedisやDBに保存する

@app.post("/jira/webhook")
def jira_webhook():
    # 1. 署名の検証（本文は加工前のバイト列で計算する）
    expected = "sha256=" + hmac.new(SECRET, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Hub-Signature", "")):
        abort(401)
    # 2. 再送による重複の排除
    delivery_id = request.headers.get("X-Atlassian-Webhook-Identifier")
    if delivery_id in seen_ids:
        return "", 200
    seen_ids.add(delivery_id)
    # 3. 重い処理はキューに渡し、ここではすぐ200を返す
    event = request.get_json()
    print(event["webhookEvent"], event.get("issue", {}).get("key"))
    return "", 200
```

受信側で重い処理を同期的に行うと、タイムアウト扱いで再送され、同じ処理が重なって走ります。

## 429エラーを防ぐレート制限の数値とRetry-Afterに従う再試行の設計

[Jira Cloudのレート制限のページ](https://developer.atlassian.com/cloud/jira/platform/rate-limiting/)によると、上限を超えると`429 Too Many Requests`が返り、`Retry-After`ヘッダーに待つべき秒数が入ります。2026年3月2日からは、Forge・Connect・OAuth 2.0（3LO）のアプリに、1時間あたりのポイントで数える新しいクォータが適用されました。APIトークンによる通信はこのポイント制の対象外で、従来どおり秒単位のバースト制限が適用されます。

| 制限の種類            | 数値（2026年11月時点）  | 対象                   |
| ---------------- | --------------- | -------------------- |
| バースト（GET・POST）   | 毎秒100リクエスト      | エンドポイントごと            |
| バースト（PUT・DELETE） | 毎秒50リクエスト       | エンドポイントごと            |
| 課題単位の書き込み        | 2秒で20回、30秒で100回 | 同じ課題への更新             |
| ポイント制（既定の共有枠）    | 1時間65,000ポイント   | Forge・Connect・3LOアプリ |

同じページの推奨は、`Retry-After`があればその秒数を最低限待ち、なければ指数バックオフにゆらぎを掛けて4回程度で諦める設計です。再試行してよいのは、冪等な要求で`Retry-After`が付いている場合に限るとされています。課題作成のPOSTを無条件に再送すると、同じ課題が二重にできます。

ポイント制の枠を使い切った場合は段階的な絞り込みが無く、UTCの毎時0分にリセットされるまで全ての要求が拒否されます。エラー応答や冪等性の考え方は[REST API設計のベストプラクティス](https://www.issoh.co.jp/tech/details/17225/)でも整理しています。

## Jira API連携を自社で組むか、AutomationやiPaaSで済ませるかの判断基準

判断の軸は「Jiraの中で完結するか」と「失敗したときに誰が気づけるか」の2つです。

課題が完了したら親の課題も進めるといった、Jiraの中で完結する処理は標準のAutomationで足ります。Slackへの通知や、フォームの回答から課題を作る程度の単発の連携は、ZapierやMakeのコネクタで十分です。iPaaSでの組み方は[iPaaS導入支援](https://www.issoh.co.jp/service/rpa/ipaas/)で扱っています。

次のどれかに当てはまる場合は、APIで自社のコードとして組むべきです。

- 基幹システムや自社サービスのDBと課題を双方向に同期し、どちらの値を正とするかの規則がある
- 1日に数千件以上の課題を作成・更新し、レート制限と再試行を自分で制御する必要がある
- Webhookの受信漏れを監査ログで追い、取りこぼしを再取得で埋める必要がある
- 顧客ごとのJiraにOAuth 2.0で接続する、自社製品の機能として提供する

逆に、件数が少なく失敗しても翌日に手で直せる処理を自前で書くのは過剰です。基幹システムとの双方向同期や、複数のSaaSをまたぐ連携の設計を外部に相談したい場合は、[API開発・システム連携](https://www.issoh.co.jp/service/system/api/)のページをご覧ください。課題管理ツール自体を見直す段階なら、APIの作りが異なる[YouTrackとJiraの違い](https://www.issoh.co.jp/column/details/3683/)も比較材料になります。

## よくある質問

Jira APIの実装を始める段階でよく出る質問をまとめました。

### Jira APIは無料プランでも使えますか？

使えます。REST APIは無料プランを含むJira Cloudの各プランで公開されており、APIトークンを発行すればすぐに呼び出しが可能です。ただしプランによってユーザー数や使える機能が違うため、APIで操作できる対象もそれに従います。レート制限のポイント制の上限はプランとユーザー数で変わりますが、APIトークンでの通信に適用されるのはバースト制限だけです。

### APIトークンが突然401になったのはなぜですか？

多くはトークンの有効期限切れです。APIトークンの期限は1〜365日で、2024年12月15日以前に作った期限なしのトークンも2026年3月14日から5月12日の間に失効しました。トークンを発行し直し、次の期限日を運用カレンダーに登録してください。

### PythonでJira APIを使うにはどのライブラリが便利ですか？

公式のREST APIはHTTPで呼べるため、この記事のコードのように`requests`だけで実装できます。PyPIには`jira`や`atlassian-python-api`といったラッパーもあり、認証や課題操作を短く書けます。ただしラッパーの版によっては旧検索APIを内部で使っている場合があるため、採用前にsearch/jqlへの対応状況を確認してください。

### JQLで取得できる件数に上限はありますか？

1回の要求で返る件数には上限があり、`maxResults`の既定は50件です。取得するフィールドを増やすと1ページの件数は減ります。全件を取るには、応答の`nextPageToken`を次の要求に渡して最後のページまで繰り返します。最後のページには`nextPageToken`が含まれないので、トークンが含まれないことが取得を終了する条件です。

### Jira Data Center版でもこの記事のコードは動きますか？

そのままでは動きません。Data Center版はAPIのパスが`/rest/api/2/`中心で、認証はパーソナルアクセストークンをBearerで渡す方式です。`search/jql`やADFはCloud版の仕様なので、Data Center版では`/rest/api/2/search`とウィキ記法の文字列を使います。

## 関連記事

- [Jiraの使い方｜スペース作成・エピックの使い分けと「使いにくい」の解消法【2026年10月】](https://www.issoh.co.jp/tech/details/7859/)：APIで扱うプロジェクト・課題タイプ・ワークフローの画面上の設計
- [JiraとGitHub連携の手順｜GitHub for Atlassian・スマートコミット・自動化](https://www.issoh.co.jp/tech/details/3548/)：コードを書かずに使える公式の連携機能
- [Confluence REST APIのv1とv2の違いと移行手順｜カーソル方式のページ送りとCQL検索の残し方](https://www.issoh.co.jp/tech/details/17390/)：同じAtlassian製品のAPIでページ送りの移行を扱った記事
- [REST APIとは？仕組みと6つの制約、SOAPとの違いをcurlの実例で解説](https://www.issoh.co.jp/tech/details/13588/)：HTTPメソッドとステータスコードの基礎
- [YouTrackとは？料金・無料プランの範囲とJiraとの違い、ワークフローとAPIの使い方【2026年10月】](https://www.issoh.co.jp/column/details/3683/)：課題管理ツールを比較する段階の判断材料

---

出典: [Jira APIの使い方｜Cloud REST API v3の認証とJQL検索・課題作成・Webhookの実装例](<https://www.issoh.co.jp/tech/details/20077/>)（株式会社一創）
