APIキーの管理

コンソールの「開発者」→「APIキー」でAPIキーを作成できます。サービスごとに必要な権限だけを持つキーをサーバー側で保管し、ダウンタイムなしでローテーションします。

APIキーは、コンソールの開発者 → APIキーにあり、作業中のアプリケーションに紐づいています。すべてのキーをパスワードと同様に扱ってください。キーは、そのアプリケーションの権限でAPIへのアクセスを許可するものです。

#キーの見つけ方

1. ビジネスコンソールにログイン

   business.didit.meにアクセスしてサインインします。

2. アプリケーションを選択

   サイドバー上部のアプリケーションカードから、対象のアプリケーションを選びます。アプリケーションごとに独自のキーがあります。

3. 「開発者」から「APIキー」を開く

   キータブには、プライマリキーを先頭にすべてのキーが一覧表示され、それぞれのアクセス権、最終使用日時、有効期限を確認できます。

#キーを作成する

Diditを呼び出すサービスごとに専用のキーを用意してください。そうすれば、それぞれのキーが何をしているかを確認でき、そのキーだけを取り消すことができます。

1. 「キーを作成」を押す

   開発者 → APIキーで操作します。

2. 名前を付けて環境を選ぶ

   キーには使用するサービスにちなんだ名前を付け、本番（実際の検証、課金あり）またはサンドボックス（テストデータ、課金なし。キーは組織のサンドボックスアプリケーションに作成されます）を選び、有効期限を選択します。有効期限は、無期限、30日後、90日後、1年後、または指定した日付から選べます。

3. アクセス権を選ぶ

   フルアクセスはすべてを読み取り・書き込みでき、自社のバックエンド向けです。読み取り専用はセッション、判定、メディアを参照できますが何も変更できず、結果だけが必要なパートナー向けです。カスタムでは、リソースごとに選択できます。サービスが判定結果だけを必要とし、身分証画像、セルフィー、動画、PDFレポートが不要な場合は、メディアを含めるのチェックを外してください。

4. 確認してシークレットをコピーする

   完全なシークレットは、キーの作成時に一度だけ表示されます。そのままシークレット管理ツールにコピーしてください。

プライマリキーは、アプリケーションの元のシークレットです。常にフルアクセスを持ち、ローテーションはできますが取り消しはできません。

#APIキーと署名シークレットは別物

混同すると分かりにくいエラーが発生するため、明確にしておく価値があります。

署名シークレットをAPIキーとして送信すると401になります。APIキーでwebhookを検証しようとすると署名が一致しません。どちらもよくある間違いです。

#テスト用のキーを取得する

本番環境に対してテストを行うことはありません。コンソールをサンドボックスに切り替えてそこでキーを作成するか、キーの作成時に環境としてサンドボックスを選んでください。サンドボックスのセッションは外部チェックをすべてモックし、課金されることも実際のユーザーデータに触れることもありません。

キーは1つのアプリケーションに属し、それに伴ってそのアプリケーションの環境に属します。サンドボックスのキーで本番の検証が作成されることはなく、本番のキーでサンドボックスの検証が作成されることもありません。シークレットを保管する場所でキーの名前を明確に区別しておく価値があります。サンドボックスでのテストをご覧ください。

#キーのローテーション

キーが漏洩した可能性がある場合は、キーを開いてキーをローテーションを選んでください。新しいシークレットが発行され、古いシークレットは24時間引き続き使用できるため、ダウンタイムなしで新しいシークレットをデプロイできます。その後は、古いシークレットを使ったリクエストはすべて401を返します。

キーを今すぐ停止しなければならない場合は、代わりにキーを取り消すを使ってください。取り消すとキーは直ちに停止し、元に戻すことはできません。プライマリキーはローテーションのみ可能です。

定期的なローテーションは良い習慣です。単なるクリックではなく、デプロイとして計画してください。

#401と403の解消

特定のワークフローに対する403は、ほとんどの場合、そのキーがそのワークフローを所有しているアプリケーションとは別のアプリケーションのものであることを意味します。コンソールでアプリケーションを切り替え、そちらのキーのいずれかを使ってください。詳細はAPIエラーとその意味をご覧ください。

#キーでできることを制限する

アクセス権はキーの作成時に選び、後からアクセス権を編集で変更できます（シークレットは変わりません。プライマリキーのアクセス権は編集できません）。読み取り専用にすればパートナーは何も変更できず、カスタムではリソース（セッション、判定、メディア、ユーザー、企業など）ごとに「なし」「読み取り」「書き込み」を設定できます。また、メディアを含めるをオフにしておけば、サービスが身分証画像、セルフィー、動画、PDFレポートをダウンロードすることを防げます。制限では、キーを一部のワークフロー、承認済みセッションのみ、またはIPアドレスのリストに限定することもできます。リスト外からのリクエストには403が返され、キーのワークフローやステータスの対象外のセッションには404が返されます。キーを開けば、そのキーでできることを正確に確認できます。キーがそのアクセス権を超える操作をすることはありません。

#チーム内で誰がキーを見られるか

キーの表示はロールに従います。このページを表示するにはAPIキーを読み取る権限が必要で、開発者ロールにはこの権限が含まれています。シークレットはコンソール上では伏せて表示されます。チームメンバーがこのページを見つけられない場合は、報告の前にまずロールを確認してください。チームメンバーの招待とロールの設定をご覧ください。

#すべての呼び出しが記録される

APIキーによるリクエストは、人物ではなくキーに紐づけて監査ログに記録されます。だからこそ、複数のサービスで1つのキーを共有していると、インシデント発生時の調査が難しくなります。利用者ごとに1つのキーを持たせるほうが、状況を把握しやすくなります。監査ログの利用をご覧ください。