発行前に確認すること
APIキーは 発行したユーザー本人の権限で Backlog を操作できる鍵だ。発行の前に、どのアカウントで発行するかを決めておく。
| やりたいこと | 発行するアカウント |
|---|---|
| 自分の担当課題を取得する、自分用の集計 | 自分のアカウント |
| チームの定期レポートをバッチで出す | 集計対象のプロジェクトすべてに参加している集計専用のユーザー(退職や異動でキーが無効にならないように) |
| 全プロジェクトを横断して集計する | 対象プロジェクトに参加している管理者権限のユーザー |
読み取りしかしないスクリプトでも、APIキー自体は更新や削除もできてしまう。権限の大きいアカウントのキーほど、保管には気をつける。
💡 会社のルールを先に確認する
組織によっては、API の利用や集計専用ユーザーの作成に申請が必要なことがある。個人設定に「API」の項目が見当たらない場合も含め、スペースの管理者に確認してから進めると後で困らない。
APIキーを発行する
- ブラウザで Backlog にログインする
- 右上の自分のアイコンをクリックし、「個人設定」 を開く
- 左のメニューから 「API」 を選ぶ
- 「メモ」 に用途がわかる名前(例:
週次レポート用(PC名))を入れて、「登録」 をクリックする - 一覧に追加された APIキーをコピーする
メモは後から「どのキーを消してよいか」を判断する手がかりになる。用途と使う場所(PC名やサーバー名) を書いておくと、不要になったキーを安心して削除できる。キーは用途ごとに分けて発行しておくと、1つが漏れたときにそれだけを消せる。
あわせて、スペースのドメインとプロジェクトキーも控えておく。
| 控えるもの | どこで見るか | 例 |
|---|---|---|
| ホスト名 | ブラウザのアドレスバー | example.backlog.com |
| プロジェクトキー | 課題キーのハイフンより前(DEV-123 なら DEV) | DEV |
キーを環境変数に入れる
キーをスクリプトに直接書くと、ファイルを共有したり Git に上げたりしたときに漏れる。この連載では 環境変数から読む 形にそろえる。
Windows(そのセッションだけ)
$env:BACKLOG_HOST = 'example.backlog.com'
$env:BACKLOG_API_KEY = 'ここに発行したキー'
$env:BACKLOG_PROJECT_KEY = 'DEV'Windows(ユーザー環境変数として保存)
毎回入力しなくて済むように、ユーザー環境変数に保存する方法もある。保存後は PowerShell や Excel を開き直す と反映される。
[Environment]::SetEnvironmentVariable('BACKLOG_HOST', 'example.backlog.com', 'User')
[Environment]::SetEnvironmentVariable('BACKLOG_API_KEY', 'ここに発行したキー', 'User')
[Environment]::SetEnvironmentVariable('BACKLOG_PROJECT_KEY', 'DEV', 'User')Linux / macOS / WSL
export BACKLOG_HOST='example.backlog.com'
export BACKLOG_API_KEY='ここに発行したキー'
export BACKLOG_PROJECT_KEY='DEV'.env ファイルを使う場合
Python や Node.js では、プロジェクトのフォルダに .env を置いて読み込む方法もよく使う。その場合は 必ず .gitignore に .env を追加する。
BACKLOG_HOST=example.backlog.com
BACKLOG_API_KEY=ここに発行したキー
BACKLOG_PROJECT_KEY=DEVcurl で接続を確認する
最初に呼ぶのは 認証ユーザー情報の取得(/api/v2/users/myself) だ。キーが正しければ、キーを発行したユーザーの情報が返る。どのプロジェクトにも依存しないので、接続確認に向いている。
curl -sS -H "Backlog-API-Key: $BACKLOG_API_KEY" \
"https://$BACKLOG_HOST/api/v2/users/myself"{
"id": 1073741824,
"userId": "takuma",
"name": "山田 太郎",
"roleType": 1,
"lang": "ja",
"mailAddress": "taro@example.com",
"lastLoginTime": "2026-11-05T00:12:34Z"
}id は数値のユーザーIDで、課題の担当者で絞り込むとき(assigneeId[])に使う。userId はログインに使う文字列で、別物なので注意する。
続けてスペース情報も取ってみる。
curl -sS -H "Backlog-API-Key: $BACKLOG_API_KEY" \
"https://$BACKLOG_HOST/api/v2/space"スペース名やタイムゾーンなどが返れば、この先の回で使う準備は整っている。
💡 Windows でも curl は使える
Windows 10 / 11 には curl.exe が入っている。ただし Windows PowerShell 5.1 では curl が Invoke-WebRequest の別名になっているため、curl.exe と拡張子まで書く。コマンドプロンプトなら curl のままでよい。
PowerShell で接続を確認する
Windows では Invoke-RestMethod を使うと、JSON を自動でオブジェクトに変換してくれるので扱いやすい。
$headers = @{ 'Backlog-API-Key' = $env:BACKLOG_API_KEY }
$me = Invoke-RestMethod -Uri "https://$env:BACKLOG_HOST/api/v2/users/myself" -Headers $headers
$me | Format-List id, userId, name, roleTypeid : 1073741824
userId : takuma
name : 山田 太郎
roleType : 1プロジェクトキーが正しいかも確かめておく。
$p = Invoke-RestMethod -Uri "https://$env:BACKLOG_HOST/api/v2/projects/$env:BACKLOG_PROJECT_KEY" -Headers $headers
"{0} {1} {2}" -f $p.id, $p.projectKey, $p.nameここで表示されるプロジェクトの 数値ID は、課題一覧の絞り込み(projectId[])で使う。プロジェクトキーから ID を引く処理は PART 04 で関数にまとめる。
ヘッダーとクエリ、どちらで渡すか
APIキーの渡し方は2通りある。
| 渡し方 | 書き方 | 評価 |
|---|---|---|
| ヘッダー | Backlog-API-Key: {キー} | 推奨。URL にキーが含まれない |
| クエリパラメータ | ?apiKey={キー} | 非推奨。URL ごとプロキシのログやブラウザの履歴に残る |
インターネット上の古い記事やサンプルの多くは ?apiKey= で書かれているが、公式ドキュメントでは現在ヘッダーでの指定が推奨されている。この連載ではすべての言語でヘッダーを使う。古いサンプルを流用するときは、ヘッダーに置き換えておくとよい。
キーの管理と失効
- キーはスクリプト・Excel ブック・チケット・チャットに直接書かない
.envを使うなら.gitignoreに入れる- 用途ごとにキーを分け、メモに用途と使う場所を書く
- 使わなくなったキーは、個人設定の API 画面から削除する
- 漏れた疑いがあれば、すぐにそのキーを削除して新しいキーを発行する
APIキーには有効期限がないため、削除しない限り使えてしまう。半年に1回など、不要なキーが残っていないかを見直す機会を決めておくと安心だ。
⚠️ Excel VBA にキーを書いて配らない
マクロ付きブックにキーを書くと、ブックを受け取った人全員がそのキーの権限で Backlog を操作できてしまう。PART 06 では、キーを環境変数から読む方法と、利用者ごとに自分のキーを入れてもらう方法を紹介する。
つまずきやすい点
| 症状 | 原因と対処 |
|---|---|
401 と "code": 11(認証エラー) | キーの貼り間違い、またはドメイン違い(.com と .jp)。ブラウザの URL と BACKLOG_HOST を見比べる |
| 環境変数が空になる | ユーザー環境変数を設定したあと、PowerShell や Excel を開き直していない |
404 と "code": 6(No project) | プロジェクトキーの間違い、または自分がそのプロジェクトに参加していない |
403 と "code": 4 | スペースに IP アドレス制限があり、接続元が許可されていない |
| 名前が文字化けする | Windows PowerShell 5.1 のコンソールの文字コードの問題。表示だけの問題なら [Console]::OutputEncoding = [Text.Encoding]::UTF8 を実行する |
エラーの読み方は PART 04、一覧は PART 11 にまとめている。
✅ 次の記事では…
PART 03 では、APIキーの代わりに OAuth 2.0 で認証する方法を扱う。複数の利用者に配るツールを作らないなら、PART 03 は飛ばして PART 04 に進んでもよい。