業務システム

Backlog APIの使い方|APIキー・OAuth2の認証と課題登録・Webhook連携の実装【2026年11月】

Backlog APIの使い方|APIキー・OAuth2の認証と課題登録・Webhook連携の実装【2026年11月】

Backlog APIは、課題やWiki、ファイルをプログラムから読み書きするためのREST APIで、問い合わせフォームから課題を自動で起票したり、基幹システムやSlackと状態を同期したりする連携の土台となる仕組みです。この記事では、APIキーとOAuth 2.0の選び分け、課題登録に必要な種別と優先度のIDの調べ方、Pythonでの登録コード、更新日を使った差分の取得、Webhookの受け方、4種別に分かれたレート制限の扱いを、2026年11月時点の公式ドキュメントとコードで示します。最後に、自社で作り込むべき連携とiPaaSで足りる連携の分かれ目を、受託開発の立場から整理します。

まとめ:Backlog API連携はヘッダ認証とID解決、Webhook受信で組む

社内の1スペースだけをつなぐなら、連携専用のユーザーでAPIキーを発行し、Backlog-API-Keyヘッダで送ります。公式サンプルの多くはキーをURLに載せていますが、アクセスログに残るためヘッダ送信に切り替えてください。利用者ごとに本人の権限で操作させたい製品を作る場合だけ、OAuth 2.0を使います。

課題の登録では、種別や優先度を名前ではなくIDで渡します。最初にプロジェクトの種別一覧と優先度一覧を取得し、名前からIDを引く表をコードに持たせるのが定石です。Backlogで起きた変更を外へ流すならWebhookで受けますが、署名による検証の仕組みが無いため、推測できないURLとHTTPSで守ります。上限は1分単位で、読み込み・更新・検索・アイコンの種別ごとに数えられるので、更新を多く出す同期処理は更新枠から逆算して組みます。

Backlog APIの全体像:スペースのURLとAPIキー・OAuth 2.0の役割

呼び出し先は、利用しているスペースのドメインに/api/v2/を付けたURLです。

backlog.jpとbacklog.comで変わるベースURLと最初の疎通確認

課題の追加APIの公式リファレンスでは、ドメインを[スペースID].backlog.com、.backlog.jp、.backlogtool.comのいずれかに置き換えるよう書かれています。どれになるかは契約した時期と地域で決まるため、ブラウザでBacklogを開いたときのアドレスをそのまま使います。

疎通確認には、上限の残りを返すGET /api/v2/rateLimitが向いています。データを変えず、どの権限のユーザーでも呼べるためです。

export BACKLOG_SPACE="example.backlog.jp"
export BACKLOG_API_KEY="xxxxxxxxxxxxxxxx"

curl -s \
  --header "Backlog-API-Key: ${BACKLOG_API_KEY}" \
  "https://${BACKLOG_SPACE}/api/v2/rateLimit"

JSONでrateLimitが返れば、ドメインとキーは正しく設定できています。401なら、キーの誤りか、スペースのドメインの取り違えを疑ってください。

APIキーをURLに載せずBacklog-API-Keyヘッダで送るべき理由

Backlog APIの認証と認可の公式ページによると、APIキーはクエリパラメータapiKeyでも、ヘッダBacklog-API-Keyでも送れます。推奨はヘッダです。URLに含めたキーは、アクセスログやブラウザの履歴に残る場合があると明記されています。

一方で、公式サポートの課題登録サンプルはRuby、Python、Go、Google Apps Script、PHP、Javaのいずれも?apiKey=をURLに付ける書き方です。サンプルを写すと、プロキシや監視ツールのログにキーが残ります。本番のコードでは必ずヘッダに移してください。

連携専用ユーザーでAPIキーを発行する運用と参加プロジェクト・権限の絞り方

APIキーはユーザーごとに発行され、そのユーザーとして動きます。担当者個人のキーで連携を作ると、異動や退職でアカウントを止めた日に連携も止まり、課題の作成者欄にもその人の名前が並びます。

連携には専用のユーザーを1人作り、必要なプロジェクトにだけ参加させます。Webhookの登録には管理者かプロジェクト管理者の権限が要りますが、日々の課題登録だけなら一般ユーザーで十分です。登録が済んだら、連携ユーザーの権限を一般ユーザーに戻しておくと、キーが漏れたときの被害を抑えられます。

同じヌーラボが提供する作図ツールCacooは、2026年11月に不正アクセスを受けて停止しましたが、Backlogへの影響はないと公表されています。Cacoo停止中にBacklog側で確かめることと、再開後に図を手元へ退避する手順はCacooの不正アクセス:問い合わせ記録約792件の流出と、停止中に利用企業が進める確認と図の退避【11月17日時点】で扱っています。

OAuth 2.0を選ぶ場面と、認可コードからトークンを得る手順

OAuth 2.0は、利用者が自分のBacklogアカウントで許可を与え、アプリがその人の権限で操作する方式です。

複数スペースに配るアプリでOAuth 2.0が要る条件と準備

OAuth 2.0が要るのは、顧客ごとに別のスペースへ入れる製品や、操作の記録を利用者本人の名前で残したい社内ツールです。社内の1スペースで連携ユーザーが代わりに操作して困らないなら、APIキーで十分です。

準備として、Backlog Developerサイトでアプリケーションを登録し、client_idとclient_secretを受け取ります。登録したリダイレクトURIと、認可要求で送るredirect_uriは完全に一致させる必要があります。

認可コードの交換と1時間で切れるアクセストークンの更新処理手順

公式の認証ページでは、利用者を/OAuth2AccessRequest.actionへ案内して認可コードを受け取り、/api/v2/oauth2/tokenへPOSTしてトークンに交換する流れが示されています。アクセストークンの有効期限は3600秒です。

# 認可コードをアクセストークンに交換する
curl -s -X POST "https://${BACKLOG_SPACE}/api/v2/oauth2/token" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=${AUTH_CODE}" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_secret=${CLIENT_SECRET}"

# 1時間後、リフレッシュトークンで更新する
curl -s -X POST "https://${BACKLOG_SPACE}/api/v2/oauth2/token" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=${REFRESH_TOKEN}" \
  --data-urlencode "client_id=${CLIENT_ID}" \
  --data-urlencode "client_secret=${CLIENT_SECRET}"

以降のAPI呼び出しにはAuthorization: Bearerヘッダでアクセストークンを付けます。トークンの期限切れは401として返るので、401を受けたら1回だけ更新して再送し、それでも401なら利用者に再認可を求める分岐にします。

Pythonで課題を登録する:種別・優先度のID解決から201応答まで

課題登録で最初につまずくのは、項目を名前で渡せない点です。

課題登録時に種別一覧と優先度一覧から名前をIDに引き当てるリクエスト

課題の追加APIの必須項目はprojectId、summary、issueTypeId、priorityIdの4つで、すべて数値のIDです。種別はプロジェクトごとに作られるため、種別一覧の取得APIのGET /api/v2/projects/{プロジェクトキー}/issueTypesで毎回プロジェクト単位に調べます。

優先度はスペース共通で、優先度一覧の取得APIの応答例では2が高、3が中、4が低です。カテゴリやマイルストーン、カスタム属性のリスト値も同じくIDで渡すため、名前とIDの対応はAPIから取り直せる作りにしておきます。

form-urlencodedで課題を追加するPythonコードとエラーの読み方

課題の追加APIはapplication/x-www-form-urlencodedで受け付け、成功すると201が返ります。次のコードはpip install requestsだけで動き、種別名と優先度名から自動でIDを引いて登録します。

import os

import requests

SPACE = os.environ["BACKLOG_SPACE"]  # 例: example.backlog.jp
BASE = f"https://{SPACE}/api/v2"
HEADERS = {"Backlog-API-Key": os.environ["BACKLOG_API_KEY"]}


def get(path, **params):
    res = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=30)
    res.raise_for_status()
    return res.json()


def add_issue(project_key, summary, issue_type, priority="中", description=""):
    """種別名と優先度名からIDを引き、課題を1件登録する"""
    project = get(f"/projects/{project_key}")
    types = {t["name"]: t["id"] for t in get(f"/projects/{project_key}/issueTypes")}
    priorities = {p["name"]: p["id"] for p in get("/priorities")}
    data = {
        "projectId": project["id"],
        "summary": summary,
        "issueTypeId": types[issue_type],
        "priorityId": priorities[priority],
        "description": description,
    }
    # data= で渡すと requests が form-urlencoded で送る
    res = requests.post(f"{BASE}/issues", headers=HEADERS, data=data, timeout=30)
    if res.status_code != 201:
        # エラーは {"errors": [{"message", "code", "moreInfo"}]} の形で返る
        raise RuntimeError(f"{res.status_code} {res.json()['errors']}")
    return res.json()["issueKey"]


if __name__ == "__main__":
    print(add_issue("SUPPORT", "問い合わせフォームからの起票テスト", "タスク"))

失敗したときの本文は、エラーレスポンスの公式ページのとおりerrors配列で返ります。codeが7なら不正なパラメータ、6なら存在しないID、5なら権限の不足です。カスタム属性はcustomField_{属性ID}という名前で送り、リスト型の属性には選択肢のIDを入れます。REST APIの呼び方全般はAPI連携の実装方法:REST・認証・エラー処理の手順をcurlとPythonのコード例で解説で扱っています。

CSVやフォームから大量登録するときの重複防止と担当者の扱い

CSVの行を順に登録する処理は、途中で止まって再実行すると同じ課題が2件できます。Backlogの課題追加には、同じ要求を一度だけ処理させるキーの仕組みがありません。CSV側に行ごとの番号を持たせ、登録した課題キーを書き戻してから次の行へ進むと、再実行しても登録済みの行を飛ばせます。

担当者はassigneeIdにユーザーのIDで入れますが、そのユーザーがプロジェクトに参加していないと登録は失敗します。フォームの入力値から担当者を決める場合は、プロジェクトの参加者一覧と突き合わせ、該当しないときは担当者を空にして登録する逃げ道を用意してください。再実行に強い作りの考え方は冪等キーとは?Idempotency-Keyの発行・保存・再生の実装と二重課金の止め方を解説が参考になります。

他ツールと同期する:更新日での差分取得とWebhookの受け口の作り方

Backlogの変更を外へ流す方法は、定期的にAPIで取りに行くか、Webhookで通知を受けるかの2つです。

updatedSinceと100件ずつのoffsetで変わった課題だけを取る手順

課題一覧の取得APIの公式リファレンスでは、updatedSinceに日付を入れて更新された課題を絞り込めます。1回で取れるのはcountの上限の100件までで、既定は20件です。

  1. 前回の同期を始めた日付を保存しておく
  2. updatedSinceにその日付、sort=updated、count=100を指定して取得する
  3. 100件返ったらoffsetを100ずつ増やして続きを取る
  4. 取得した課題のupdatedを見て、前回処理済みのものを飛ばす
  5. すべて処理し終えてから、今回の開始日付を保存する

updatedSinceは日単位の指定なので、同じ日に2回同期すると、1回目に処理した課題がまた返ります。課題ごとに最後に処理したupdatedの値を持ち、それより新しいものだけを反映させてください。

Webhookの登録APIとactivityTypeIdsで通知を課題の変更に絞る設定

即時性が要るならWebhookです。Webhookの追加APIはPOST /api/v2/projects/{プロジェクトキー}/webhooksで、実行できるのは管理者とプロジェクト管理者です。allEventをfalseにし、activityTypeIds[]で通知したい出来事を選びます。

curl -s -X POST \
  --header "Backlog-API-Key: ${BACKLOG_API_KEY}" \
  "https://${BACKLOG_SPACE}/api/v2/projects/SUPPORT/webhooks" \
  --data-urlencode "name=基幹システム連携" \
  --data-urlencode "hookUrl=https://hooks.example.com/backlog/${WEBHOOK_TOKEN}" \
  --data-urlencode "allEvent=false" \
  --data-urlencode "activityTypeIds[]=1" \
  --data-urlencode "activityTypeIds[]=2" \
  --data-urlencode "activityTypeIds[]=3"

番号は最近の更新の取得APIの種別一覧と対応しており、1が課題の追加、2が課題の更新、3が課題へのコメント、4が課題の削除です。Wikiやプルリクエストの通知まで受けると処理が増えるだけなので、必要な番号だけを指定します。

署名の無いWebhookを推測できないURLとHTTPSで受けるPythonコード

Webhookの追加APIのパラメータは名前、説明、通知先URL、通知の範囲だけで、署名用のシークレットを登録する項目がありません。受け口では、URLのパスに推測できない文字列を入れ、届いた値と定数時間で比べて正規の通知かを判断します。

import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
TOKEN = os.environ["WEBHOOK_TOKEN"]  # secrets.token_urlsafe(32) などで作った値
ISSUE_EVENTS = {1, 2, 3, 4}  # 課題の追加・更新・コメント・削除


def enqueue(event):
    # 実運用ではキューに積み、別プロセスで基幹システムへ反映する
    print(event["type"], event["project"]["projectKey"])


@app.post("/backlog/<token>")
def receive(token):
    if not hmac.compare_digest(token, TOKEN):
        abort(404)  # 不一致は存在しないURLとして扱う
    event = request.get_json(silent=True) or {}
    if event.get("type") in ISSUE_EVENTS:
        enqueue(event)
    return "", 204

URLはアクセスログに残りやすいので、受け口の手前のロードバランサーやリバースプロキシで、このパスをログから外す設定も入れてください。通知の中身は種別ごとに項目が違うため、課題キーだけを取り出してAPIで課題を取り直すと、項目の差に悩まずに済みます。受け口の作り全般はWebhookの作り方と実装方法|受信側の署名検証・冪等性と送信側の再送をNode.js・Pythonで解説で解説しています。

レート制限の扱い:読み込み・更新・検索・アイコンの4種別と429の再送

上限は1分あたりの回数で、ユーザー単位にかかります。

rateLimit APIとX-RateLimit系ヘッダで種別ごとの残りを確かめる方法

レート制限の公式ページによると、上限は読み込み、更新、検索、アイコンの4種別に分かれ、Freeプランと有料プランで値が異なります。現在の値はレート制限情報の取得APIで確かめられ、応答例では読み込み600回、更新150回、検索150回、アイコン60回です。

ヘッダ 意味
X-RateLimit-Limit 1分間に受け付ける最大回数
X-RateLimit-Remaining リセットまでに使える残り回数
X-RateLimit-Reset 計測がリセットされる時刻(UNIX時間)

応答例の値はあくまで例で、契約や負荷の状況で変わります。システムの負荷が高いときは、より厳しい上限がかかる場合もあると公式ページは書いています。連携を作る前に自分のスペースで/api/v2/rateLimitを呼び、実際の値を設計書に残してください。

429を受けたら1分待つ再送処理と大量更新を夜間に回す判断基準

上限を超えると429が返り、公式ページは1分たってからの再送を勧めています。待ち時間を詰めたい場合はX-RateLimit-Resetの時刻まで待つ実装にします。

課題の一括登録や状態の一斉更新は、すべて更新の枠を消費します。更新の上限が1分150回なら、千件の課題を書き換える処理は最短でも7分近くかかり、その間は同じユーザーのほかの更新も詰まります。日中に人が使う連携と同じユーザーで大量更新を走らせず、夜間に回すか、ユーザーを分けてください。上限の一般的な設計はAPIレート制限(レートリミット)とは?5方式の比較と429設計・分散実装【2026年版】にまとめています。

受託開発の視点で見るBacklog連携を作り込む条件とiPaaSで足りる場面

ここからは、連携開発を受ける立場からの判断です。分かれ目は、項目の対応づけの複雑さと件数にあります。

作り込むべき条件:基幹システムとの双方向同期と項目の対応表の管理

次のどれかに当てはまるなら、APIで個別に開発します。基幹システムや自社のWebサービスと、課題の状態を双方向に同期したいとき。カスタム属性やカテゴリの対応表を持ち、名前の変更にも追従させたいとき。1日に数百件以上を登録し、失敗した行だけを再送して記録を残したいとき。どれも画面の設定で組むツールでは保守しにくい部分です。

個別開発には、トークンやキーの管理、Webhookの監視、上限の調整という保守が続きます。要件の整理から実装、保守までをまとめて頼みたい場合は、API開発・システム連携サービスで相談を受け付けています。

作り込まない場面:通知を流すだけの連携とAIエージェントからの操作

課題が作られたらチャットに流す、フォームの回答を1件ずつ課題にする、といった片方向で1日数十件までの連携に個別開発は過剰です。iPaaSなら画面の設定で組め、担当者が自分で直せます。料金の数え方はiPaaSとは?API・RPA・ETLとの違いと料金の数え方【2026年11月】で確認してください。

開発者がClaudeやCursorなどのAIエージェントから課題を検索・起票したいだけなら、コードを書く必要はありません。公式のMCPサーバーを入れて権限を絞る方法をBacklog MCPサーバーの導入手順と権限設計|64ツールの絞り込みと削除系の封じ方【2026年10月】で解説しています。

Backlog APIのよくある質問:無料プラン・APIキーの発行・GitHub連携

Backlog APIで連携を作る前によく寄せられる質問に、2026年11月時点の公式ドキュメントをもとに回答します。

Backlogの無料プランでもAPIは使えますか?

使えます。公式のレート制限ページはFreeプランと有料プランで上限が異なると書いており、無料でもAPIの呼び出し自体は可能です。ただし契約プランで使えない機能を呼ぶと、エラーコード2のLicenceErrorが返ります。使いたい機能が自分のプランに含まれるかを先に確かめ、上限は/api/v2/rateLimitで実際の値を見てください。

APIキーはどこで発行し、漏れたらどうすればよいですか?

APIキーはBacklogの個人設定にあるAPIの画面から、ユーザーごとに発行します。漏れた疑いがあれば、同じ画面でそのキーを削除し、新しいキーを発行して連携の設定を差し替えてください。キーは発行したユーザーの権限で動くため、連携専用のユーザーで発行しておけば、削除しても個人の業務には響きません。

APIキーとOAuth 2.0はどちらを選べばよいですか?

社内の1スペースに対して、連携専用ユーザーとして操作してよいならAPIキーで足ります。顧客ごとに別のスペースへ配る製品や、操作の記録を利用者本人の名前で残したい場合に選ぶ方式はOAuth 2.0です。OAuth 2.0はアクセストークンが1時間で切れるため、リフレッシュトークンでの更新処理まで作る必要があります。

GitHubのプルリクエストとBacklogの課題はAPIでつなげますか?

つなげます。GitHubのWebhookでプルリクエストの作成や統合を受け、ブランチ名やタイトルに含まれる課題キーを取り出して、Backlogの課題にコメントを追加したり状態を更新したりする形が一般的です。コメントの追加と状態の更新はどちらも更新の枠を使うので、プルリクエストが多いチームでは上限の残りを見ながら送ってください。

スプレッドシートやGoogle Apps Scriptから課題を一括登録できますか?

できます。公式サポートの課題登録サンプルにもGoogle Apps Scriptの例があり、UrlFetchApp.fetchで課題の追加APIを呼ぶ形です。ただしサンプルはAPIキーをURLに載せているので、headersオプションでBacklog-API-Keyを送る書き方に直します。キーはスクリプトのコードに書かず、スクリプトプロパティに保存してください。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.13 テックブログ 宝くじ公式サイト不正アクセス:4,436名の対象確認とパスワード再設定、変更された仕組み
  2. 2026.11.14 テックブログ Gitの脆弱性6件:CVE-2026-111760の再帰クローン対策と2.56.1への更新手順
  3. 2026.11.14 テックブログ ImageMagickの脆弱性VU#580079:policy.xmlの許可リスト設定と影響判定の手順
  4. 2025.04.09 コラム ダブルバーレル質問(二重質問)とは?例文と直し方、多重質問・誘導質問との違い
  5. 2026.11.13 テックブログ KARTEの不正アクセス:メールアドレス79,249件と連携認証情報の漏えい、利用企業の対応手順【11月16日時点】

RELATED POSTS 関連記事

目次