発行前に確認すること

APIキーは 発行したユーザー本人の権限で Backlog を操作できる鍵だ。発行の前に、どのアカウントで発行するかを決めておく。

やりたいこと発行するアカウント
自分の担当課題を取得する、自分用の集計自分のアカウント
チームの定期レポートをバッチで出す集計対象のプロジェクトすべてに参加している集計専用のユーザー(退職や異動でキーが無効にならないように)
全プロジェクトを横断して集計する対象プロジェクトに参加している管理者権限のユーザー

読み取りしかしないスクリプトでも、APIキー自体は更新や削除もできてしまう。権限の大きいアカウントのキーほど、保管には気をつける。

💡 会社のルールを先に確認する

組織によっては、API の利用や集計専用ユーザーの作成に申請が必要なことがある。個人設定に「API」の項目が見当たらない場合も含め、スペースの管理者に確認してから進めると後で困らない。

APIキーを発行する

  1. ブラウザで Backlog にログインする
  2. 右上の自分のアイコンをクリックし、「個人設定」 を開く
  3. 左のメニューから 「API」 を選ぶ
  4. 「メモ」 に用途がわかる名前(例:週次レポート用(PC名))を入れて、「登録」 をクリックする
  5. 一覧に追加された APIキーをコピーする

メモは後から「どのキーを消してよいか」を判断する手がかりになる。用途と使う場所(PC名やサーバー名) を書いておくと、不要になったキーを安心して削除できる。キーは用途ごとに分けて発行しておくと、1つが漏れたときにそれだけを消せる。

あわせて、スペースのドメインとプロジェクトキーも控えておく。

控えるものどこで見るか例
ホスト名ブラウザのアドレスバーexample.backlog.com
プロジェクトキー課題キーのハイフンより前(DEV-123 なら DEV)DEV

キーを環境変数に入れる

キーをスクリプトに直接書くと、ファイルを共有したり Git に上げたりしたときに漏れる。この連載では 環境変数から読む 形にそろえる。

Windows(そのセッションだけ)

PowerShell
$env:BACKLOG_HOST = 'example.backlog.com'
$env:BACKLOG_API_KEY = 'ここに発行したキー'
$env:BACKLOG_PROJECT_KEY = 'DEV'

Windows(ユーザー環境変数として保存)

毎回入力しなくて済むように、ユーザー環境変数に保存する方法もある。保存後は PowerShell や Excel を開き直す と反映される。

PowerShell
[Environment]::SetEnvironmentVariable('BACKLOG_HOST', 'example.backlog.com', 'User')
[Environment]::SetEnvironmentVariable('BACKLOG_API_KEY', 'ここに発行したキー', 'User')
[Environment]::SetEnvironmentVariable('BACKLOG_PROJECT_KEY', 'DEV', 'User')

Linux / macOS / WSL

bash
export BACKLOG_HOST='example.backlog.com'
export BACKLOG_API_KEY='ここに発行したキー'
export BACKLOG_PROJECT_KEY='DEV'

.env ファイルを使う場合

Python や Node.js では、プロジェクトのフォルダに .env を置いて読み込む方法もよく使う。その場合は 必ず .gitignore に .env を追加する。

.env
BACKLOG_HOST=example.backlog.com
BACKLOG_API_KEY=ここに発行したキー
BACKLOG_PROJECT_KEY=DEV

curl で接続を確認する

最初に呼ぶのは 認証ユーザー情報の取得(/api/v2/users/myself) だ。キーが正しければ、キーを発行したユーザーの情報が返る。どのプロジェクトにも依存しないので、接続確認に向いている。

bash
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 はログインに使う文字列で、別物なので注意する。

続けてスペース情報も取ってみる。

bash
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 を自動でオブジェクトに変換してくれるので扱いやすい。

PowerShell
$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, roleType
出力例
id       : 1073741824
userId   : takuma
name     : 山田 太郎
roleType : 1

プロジェクトキーが正しいかも確かめておく。

PowerShell
$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 に進んでもよい。

→ PART 03 — OAuth 2.0で認証するへ