# APIキーの管理

Source: https://help.didit.me/ja/account-organization/api-keys
Updated: 2026-10-12

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

**開発者 → APIキー**にあり、選択中のアプリケーションに紐づいています。すべてのアプリケーションには**プライマリ**キーがあり、サービスごとに1つずつ、それぞれ独自のアクセス権と有効期限を持つキーを追加で作成できます。キーはサーバー側のシークレットであり、フロントエンドのコードやアプリのバンドルに含めてはいけません。

[Video: APIキーの設定とWebhookのテスト - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: KYC API連携を5ステップで：Cursor用AIセットアッププロンプト付き - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

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

## キーの見つけ方

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

   [business.didit.me](https://business.didit.me)にアクセスしてサインインします。

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

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

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

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

![キーの一覧が表示されたDiditコンソールのAPIキーページ](https://help.didit.me/screenshots/api-keys-light.webp)

*このアプリケーションのすべてのキー：先頭がプライマリキーで、その後に作成したキーが続きます。*

## キーを作成する

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

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

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

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

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

3. **アクセス権を選ぶ**

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

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

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

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

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

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

| | 用途 | 単位 |
|---|---|---|
| **APIキー** | `x-api-key`ヘッダーでDiditへの呼び出しを認証する | アプリケーションごと、必要な数だけ |
| **Webhook署名シークレット** | 受信したwebhookが本当にDiditから送られたものかを検証する | webhookの**エンドポイント**ごと |

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

> **Warning:** APIキーはシークレットです。フロントエンドのコード、公開リポジトリ、モバイルアプリのバンドルには絶対に含めないでください。サーバー側だけで保管してください。配布済みのアプリバンドルに含まれたキーは、攻撃者に渡ったキーと同じです。
> [API認証](https://docs.didit.me/getting-started/api-authentication)をご覧ください。

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

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

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

## キーのローテーション

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

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

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

## 401と403の解消

| エラー | 原因 | 対処法 |
|---|---|---|
| `401` | キーが存在しない、形式が誤っている、期限切れ、取り消し済み、またはローテーションから24時間以上経過している | 該当アプリケーションの**開発者 → APIキー**でキーを確認してください。余分な空白や引用符が入っていないか、署名シークレットを貼り付けていないかを確認してください |
| `403` | キーは有効だが、この呼び出しは許可されていない | 多くの場合、アプリケーションの取り違え、本番キーでのサンドボックス専用フィールド（またはその逆）、キーに付与されていないアクセス権（例えば、読み取り専用キーで書き込もうとした場合）、アカウントで有効になっていない機能のいずれかです |

特定のワークフローに対する`403`は、ほとんどの場合、そのキーがそのワークフローを所有しているアプリケーションとは**別のアプリケーション**のものであることを意味します。コンソールでアプリケーションを切り替え、そちらのキーのいずれかを使ってください。詳細は[APIエラーとその意味](https://help.didit.me/ja/integration/api-errors)をご覧ください。

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

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

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

キーの表示はロールに従います。このページを表示するにはAPIキーを読み取る権限が必要で、**開発者**ロールにはこの権限が含まれています。シークレットはコンソール上では伏せて表示されます。チームメンバーがこのページを見つけられない場合は、報告の前にまずロールを確認してください。[チームメンバーの招待とロールの設定](https://help.didit.me/ja/account-organization/team-members-and-roles)をご覧ください。

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

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