> 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/api/authentication.md).

# 認証

外部 API へのリクエストは、すべて組織単位の APIキーで認証します。

## APIキーを発行する

1. Organization Admin（組織管理者）の権限でイマーシブトレーニングプラットフォームにサインインします。
2. 組織設定の「APIキー」タブを開きます。
3. 「APIキーを作成」をクリックします。
4. キーの名前と説明を入力します。
5. 発行されたキーをコピーし、安全な場所に保管します。

画面での管理方法は「[APIキーの管理](https://docs.digitalhumans.jp/itp-guide/initial-setup/api-keys.md)」もご覧ください。

{% hint style="info" %}
**キーの有効期間**\
キーは削除するまで有効で、期限切れになることはありません。組織は複数のキーを同時に持てるため、既存のキーと並行して新しいキーを導入できます。
{% endhint %}

{% hint style="success" %}
**キーを入れ替える（ローテーション）**\
新しいキーを発行し、連携システムを新しいキーに切り替えてから、「APIキー」タブで古いキーを削除します。キーを削除した時点で、そのキーは受け付けられなくなります。キーが漏えいした可能性がある場合は、すぐに削除してください。
{% endhint %}

{% hint style="success" %}
**発行済みのキーをあとから確認する**\
発行済みのキーは、「APIキー」タブからいつでも再度コピーできます。一覧には一部を伏せた値が表示され、コピー操作でキー全体が取得されます。このタブにアクセスできるのは必要な管理者だけに限定し、キーはシークレット管理の仕組みに保管して、連携システムが実行時に読み込むようにしてください。
{% endhint %}

## APIキーを使う

すべてのリクエストで、`Authorization` ヘッダーに APIキーを Bearer トークンとして付けます。

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

APIキーは組織単位です。リクエストは、キーを所有する組織に自動的にひも付けられます。

## ベースパス

```
https://training.uneeq.io/api/external/v1/organization/{organizationID}
```

`{organizationID}` を、お客様の組織 ID に置き換えます。組織 ID は `org_abc123` のような識別子で、UUID ではありません。

## コード例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{organizationID}/users/page/1?limit=25" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

BASE_URL = "https://training.uneeq.io/api/external/v1/organization/{org_id}"
API_KEY = "your-api-key-here"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    f"{BASE_URL}/users/page/1",
    headers=headers,
    params={"limit": 25}
)

print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const BASE_URL = 'https://training.uneeq.io/api/external/v1/organization/{orgID}';
const API_KEY = 'your-api-key-here';

const response = await fetch(`${BASE_URL}/users/page/1?limit=25`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);
```

{% endtab %}
{% endtabs %}

他のページのコード例にある `BASE_URL`・`headers`・`API_KEY` は、ここで定義したものを指します。

## エラーレスポンス

### 401 Unauthorized

APIキーが指定されていない、正しくない、またはこの組織のものではない場合に返されます。ボディは `message` ではなく `error` キーです。

```json
{
  "error": "No api key provided"
}
```

### よくある原因

| 原因                      | 対処                                                               |
| ----------------------- | ---------------------------------------------------------------- |
| `Authorization` ヘッダーが無い | リクエストに `Authorization: Bearer your-api-key-here` を付ける            |
| APIキーが正しくない             | 発行したキーと一致しているか確認する                                               |
| APIキーが削除されている           | 管理画面で新しいキーを発行する                                                  |
| URL の組織 ID が違う          | `{organizationID}`（例: `org_abc123`。UUID ではない）が、キーを所有する組織のものか確認する |

## キー管理のベストプラクティス

* **入れ替えは「発行してから削除」の順で**: 新しいキーを発行し、連携システムを切り替えてから、古いキーを削除します。
* **環境変数を使う**: APIキーをソースコードに直接書かないでください。
* **利用状況を確認する**: 連携システムと APIキーの使われ方を定期的に見直し、想定外の利用がないか確認します。
* **無効にするには削除する**: キーを削除すると受け付けられなくなります。キーに有効期限は無いため、使わなくなったキーは削除してください。
