API キー

API キーを使用すると、badges.ninja の REST API にプログラムからアクセスできます。バッジの作成、発行、管理を、ご自身のアプリケーションから自動化できます。

API キーを作成する

1. サイドバーから API Keys ページを開きます。
2. Create API Key をクリックします。インラインフォームが開きます。

3. キーに名前を付けて Create をクリックします。完全なキーが緑色のバナーに一度だけ表示されます。

4. すぐにキーをコピーしてください — 完全なキーが表示されるのは一度だけです。紛失した場合は、新しいキーを作成する必要があります。バナーを閉じると、ダッシュボードにはキーのプレフィックス (例: bws_a1b2c3d4...) のみが表示されます。完全なキーはリクエストの認証のためにサーバー側に保存されています。

各行には、キーの作成日時と、使用後は last used のタイムスタンプも表示されるため、使われていないキーを見つけられます。

アクセススコープ

キーを作成するときに、読み取り専用にするか、フルアクセスのままにするかを選択できます。

スコープ	許可される操作
フルアクセス (デフォルト)	読み取りおよび書き込み — データの一覧表示、作成、発行、更新、削除。
読み取り専用	安全な GET リクエストのみ。変更を伴うリクエスト (POST、PUT、PATCH、DELETE) は 403 Forbidden で拒否されます。

データを読み取るだけの連携 (レポート、ダッシュボード、バックアップ) には読み取り専用キーを使用してください。キーが漏えいしても何も変更されません。作成フォームで Read-only key にチェックを入れます。読み取り専用キーは一覧に Read-only バッジが表示されます。スコープが導入される前に作成されたキーは、フルアクセスのままです。

キーの形式

API キーは bws_ プレフィックスに続く 32 文字の 16 進数文字列です。

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

リクエストで API キーを使用する

すべての API リクエストの X-Api-Key ヘッダーに API キーを含めてください。

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

API 認証の詳細については、認証ページをご覧ください。

プランごとのキー数の上限

作成できる API キーの数はプランによって異なります。

プラン	API キーの上限
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

キーの有効期限

すべての API キーは作成から 1 年後に失効します。失効したキーはリクエストを認証しなくなり、削除された場合と同じ状態になります。中断を避けるため、古いキーが失効する前に新しいキーを作成してください。

キーを削除する

1. API Keys ページを開きます。
2. 削除したいキーを探します。
3. Delete をクリックします。
4. 削除を確認します。

削除すると、キーはただちに使えなくなります。そのキーを使用しているアプリケーションには認証エラーが返されます。