> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/itp-guide/initial-setup/api-keys.md).

# APIキーの管理

APIキーは、お客様のシステムからイマーシブトレーニングプラットフォームの API を呼び出すときに使う認証情報です。ユーザーの一括登録、チームの管理、受講データの取り出しなどを、プログラムから行えるようになります。

APIキーの発行と管理は、Organization Admin（組織管理者）が行います。

{% hint style="warning" %}
APIキーを持っていれば、API を通じて組織のデータにすべてアクセスできます。\
キーは安全な場所に保管し、漏えいのおそれがある場合はすぐに削除してください。
{% endhint %}

## APIキーの特徴

* APIキーは組織ごとに発行されます。キーを使ったリクエストは、キーを発行した組織に対するものとして扱われます。
* キーに有効期限はありません。削除するまで有効です。
* 1つの組織で、複数のキー（最大10個）を同時に持てます。新しいキーを、いまのキーと並行して使い始められます。

## APIキーを発行する

1. Organization Admin のアカウントでログインします。
2. 組織設定の「APIキー」タブを開きます。
3. 「APIキーを作成」をクリックします。
4. 「新しいAPIキーを作成」が表示されたら、キーの名前と説明を入力し、「作成」をクリックします。用途や連携先のシステムが分かる名前にしておくと、あとで管理しやすくなります。
5. 発行されたキーをコピーし、安全な場所に保管します。

## 発行済みのキーをもう一度コピーする

発行済みのキーは、「APIキー」タブからいつでもコピーし直せます。一覧ではキーの一部が伏せて表示され、コピー操作でキー全体を取得できます。「APIキー」タブには、API の「接続URL」と「組織ID」も表示されます。

{% hint style="info" %}
このタブを開ける管理者は、必要な人だけに絞ってください。\
連携するシステムでは、キーをシークレット管理の仕組み（環境変数や秘密情報の保管サービスなど）に保存し、実行時に読み込む形をおすすめします。
{% endhint %}

## キーを入れ替える（ローテーション）

キーを新しいものに入れ替えるときは、次の順で行います。

1. 新しいキーを発行します。
2. 連携しているシステムを、新しいキーに切り替えます。
3. 「APIキー」タブで、古いキーを削除します。

## キーを無効にする（削除）

キーを削除すると、そのキーは受け付けられなくなります。キーには有効期限がないため、使わなくなったキーは削除してください。漏えいのおそれがあるキーは、すぐに削除してください。

{% hint style="info" %}
キーの削除は取り消せません。削除する前に、連携しているシステムがそのキーを使っていないことを確認してください。
{% endhint %}

## 運用のポイント

* キーをソースコードに直接書かず、環境変数などから読み込んでください。
* 連携の状況とキーの利用状況を定期的に見直し、想定外の利用がないか確認してください。
* 入れ替えは「新しいキーを発行 → 切り替え → 古いキーを削除」の順で行ってください。

## キーの使い方

API を呼び出すときは、すべてのリクエストの `Authorization` ヘッダーに、APIキーを Bearer トークンとして指定します。

```
Authorization: Bearer your-api-key-here
```

接続先の URL、組織 ID の指定方法、コード例、エラーの対処は [API の「認証」](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)を、API 全体の説明は [API の概要](https://docs.digitalhumans.jp/itp-guide/api.md)をご覧ください。リクエスト数の上限はキーごとに決まっています。詳しくは[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)をご覧ください。
