> Agent-readable docs index: /llms.txt. Fetch only the needed Markdown pages first; use /docs.zip only for broad search after checking /docs-manifest.json or /docs.zip.sha256.

# 認証

## 認証方法

認証関連を除くすべてのAPIリクエストには、認証トークン（Auth Token）が必要です。

認証トークンはHTTPヘッダーに含める必要があります。

```http request
Authorization: {{Auth Token}}
```

_\* `Bearer` などのプレフィックスは不要です。_

<details>
<summary>主要概念</summary>
<dl>
<dt>API Key</dt>
<dd><strong>定義：</strong>KOSチームがクリニックに発行するサーバー用認証キーです。<br /><strong>説明：</strong>認証トークンを取得するための入力値であり、クライアントに公開せず、サーバーサイドのみで使用する必要があります。</dd>
<dt>認証トークン（Auth Token）</dt>
<dd><strong>定義：</strong>APIリクエスト時に<code>Authorization</code>ヘッダーに含めて送信するトークンです。<br /><strong>説明：</strong>認証関連のAPIを除くすべてのリクエストに必要です。一定時間が経過すると満了する場合があり、満了したトークンで呼び出すと<code>401</code>レスポンスが返されます。</dd>
<dt>認証トークン交換</dt>
<dd><strong>定義：</strong>API Keyを認証トークンに切り替えるサーバーサイドの手順です。<br /><strong>説明：</strong>クライアントで実行するとAPI Keyが公開される恐れがあるため、必ずサーバーのみで呼び出す必要があります。</dd>
<dt>Authorizationヘッダー</dt>
<dd><strong>定義：</strong>認証トークンを伝達するHTTPヘッダーです。<br /><strong>説明：</strong>値には認証トークンのみを含め、<code>Bearer</code>などのプレフィックスは付けません。</dd>
</dl>
</details>

<Callout type="danger">
<p><strong>APIキーおよび認証トークンを絶対にクライアントに公開しないでください。</strong></p>
<p>クライアントに公開されたり、クライアント側で保存されたりしないよう注意してください。</p>
<p>認証トークンの交換も、絶対にクライアント側で行ってはなりません。</p>
<p>公開された場合、悪意のあるユーザーが認証トークンを取得してAPIを使用する可能性があります。</p>
<p>公開された場合は、直ちにKOSチームを通じて新しいAPIキーを発行してもらう必要があります。</p>
</Callout>

認証トークンを発行するには、KOSチームから提供されたAPIキーが必要です。

[認証トークン交換](/docs/openapi/exchange-token) APIを通じて認証トークンを発行できます。

## 認証フロー

1. KOSチームからAPIキーを発行してもらいます。
2. サーバーサイドで [認証トークン交換](/docs/openapi/exchange-token) APIにAPIキーを渡して認証トークンを発行します。
3. 発行された認証トークンを以降のAPIリクエストの `Authorization` ヘッダーに含めて呼び出します。

<Callout type="info">
<p>APIキーの発行、認証トークンの交換、および認証トークンを使用するすべての呼び出しは、サーバーサイドでのみ行う必要があります。</p>
</Callout>

## トークンの有効期間

認証トークンは一定時間が経過すると失効します。有効期間はKOSのポリシーにより異なる場合があります。

## トークン失効時の処理

失効したトークンでAPIを呼び出すと、`401` ステータスコードが返されます。

その場合、[認証トークン交換](/docs/openapi/exchange-token) APIを再度呼び出して新しいトークンを発行し、リクエストを再試行してください。

## トークン管理戦略

リクエストごとにトークンを新たに交換するのではなく、以下の戦略での管理を推奨します。

- **再利用**: 発行されたトークンをサーバーサイドのメモリまたはキャッシュに保管し、再利用します。
- **401対応**: APIリクエストが `401` レスポンスを返した場合、トークンを再度交換して更新し、失敗したリクエストを再試行します。

トークンの値をパースして失効を判断せず、APIの `401` レスポンスで失効を処理してください。

## APIキーの管理

- APIキーはサーバーサイドの環境変数またはシークレットストアに保管し、コードリポジトリやクライアントには含めないでください。
- APIキーが漏洩した、または漏洩が疑われる場合は、直ちにKOSチームを通じて新しいAPIキーを発行してもらいます。

## セキュリティ上の注意

認証関連APIを除くすべてのOpenAPIリクエストでは、`Authorization`ヘッダーに認証トークン(Auth Token)を含める必要があります。

API Keyと認証トークンをクライアントに露出しないでください。認証トークン交換もブラウザやモバイルクライアントで実行してはいけません。

API KeyとAuth TokenはKOS Connectの`appId`とは異なります。OpenAPI認証情報はサーバー側だけで扱い、露出した場合はすぐにKOSチームを通じて新しいAPI Keyを発行してください。

## エンドポイント

- [認証トークン交換](/ja/docs/openapi/exchange-token.md): `POST /open/authorization/commands/exchange-token`