認証

ChatWalaʻau には、補い合う2つの認証の仕組みがあります。呼び出し元ごとに発行する API キー（Bearer トークン）と、クラウドでの利用向けの任意の Web サインイン（ユーザー名とパスワード）です。

v0.215.0 の破壊的変更

.env の API_KEY と RESPONSES_API_KEY は読まれなくなりました。値が残っていると、起動時の警告でその名前を出し、値は無視します。これらを使っていた呼び出し元は、管理キー（下記）を渡すまで 401 になります。古い値の取り込みはありません。

API キー

呼び出し元ごとに専用のキーを渡します。キーは、名前、1つのスコープ、任意の有効期限、有効/無効の切り替えを持ちます。

スコープ	呼べるもの	渡す相手
`responses`	`POST /v1/responses` だけ	会社サイトのサーバー、外部アプリ
`api`	キー管理以外のすべての API（`/api/*`、`/ag-ui/`、WebSocket、`/v1/responses`）	CLI、自動化
`admin`	キー管理を含むすべて	キーを管理する必要がある場合だけ

キーを作る

API Keys 画面: サイドバー下部の鍵のアイコン（広い画面のみ）から開きます。ブラウザでサインインしているときか、同じマシンで使っているときに表示されます。ここでキーの発行、編集、無効化 / 有効化、再発行、削除ができ、各操作の間はスピナーが表示されます。
サーバー上の CLI（Web サインインのないサーバーで最初のキーを作る方法でもあります）:

chatwalaau keys create --name company-site-bff --scope responses --expires-days 90
chatwalaau keys list
chatwalaau keys disable <id>    # 残したまま拒否する
chatwalaau keys enable <id>
chatwalaau keys reissue <id>    # 新しい秘密の値。古い値はすぐ使えなくなる
chatwalaau keys delete <id>

秘密の値（cwk_<id>_...）は、発行時と再発行時に一度だけ表示されます。保存されるのは SHA-256 のハッシュだけで、 API_KEYS_FILE で指定したファイルに入り、その隣にすべての変更の監査ログが残ります。

API_KEYS_FILE=api_keys.jsonc          # 既定値。Azure App Service では /home の下のパスにする
# APP_REQUIRE_AUTH_ON_LAN=true         # 既定値: キーのない LAN からのアクセスを拒否する

変更は再起動なしで、次のリクエストから効きます。api_keys.jsonc とその監査ログは、Git、Docker のビルド、公開リポジトリへの同期の対象外です。

どこで何が受け付けられるか

同じマシンのクライアント（127.0.0.1、::1、localhost）は、キーなしで書き込みのエンドポイントと AG-UI のストリームを通ります。 APP_HOST=0.0.0.0 でも、localhost での開発は設定不要のままです。

クライアントのアドレス	`APP_REQUIRE_AUTH_ON_LAN`	有効なキーか Web サインイン	`/api/*` と `POST /ag-ui/` の結果
ループバック	任意	任意	許可
LAN	`false`	任意	許可（運用者が明示的に開放）
LAN	`true`	どちらもない	503
LAN	`true`	あり	`api` / `admin` のキー（またはサインインの Cookie）が必要

/v1/responses は、クライアントのアドレスに関わらず、常にキー（どのスコープでも可）が必要です。有効なキーがなければ 503 です。
存在しない、期限切れ、無効化されたキーは 401、スコープが足りないキーは 403 です。
キー管理は、Web サインイン、同じマシン、admin のキーのどれかでのみ使えます。APP_REQUIRE_AUTH_ON_LAN=false の公開モードでは使えず、自分より上のスコープは付与できません。
APP_REQUIRE_AUTH_ON_LAN は .env に残ります。API Keys 画面では読み取り専用で表示されます。

キーごとの上限

v0.216.0 から、キーごとに /v1/responses の上限を持たせられます。API Keys 画面の Limits for /v1/responses で設定します。

項目	意味
`requests_per_minute` / `requests_per_day` / `requests_per_month`	このキーで行えるリクエスト数
`total_tokens_per_day` / `total_tokens_per_month`	このキーで使える入力と出力のトークンの合計

空欄か 0 なら、このキーの上限はありません。App Settings の全体の上限もあわせて効きます（利用上限）。画面には、キーごとの今日と今月の使用量が表示されます。上限を超えたキーは key_ で始まる code の 429 を受け取ります。ほかのキーは使い続けられるので、漏れたキー1本が枠を使い切ることはありません。HTTP では POST か PATCH /api/api-keys に "limits": {...} を付けて送ります。 null で解除します。

キーごとのエージェントと会話

v0.218.0 から、キーをカスタムエージェントに結びつけ、/v1/responses の会話の保存方法を選べます。 API Keys 画面の Agent and conversations for /v1/responses で設定します。

項目	意味
Agent	None（リクエストがモデルを選ぶ）、またはカスタムエージェント。結びつけたキーはそのエージェントだけで動く
Conversations	Saved（チャット履歴に出る）、または Temporary（一覧に出ず、保存期間を過ぎると消える）

一覧では、strict のエージェントに (documents only)、問題のあるエージェントに (has problems) が付きます。問題のあるエージェントに結びつけたキーは、直るまで 503 になります。HTTP では POST か PATCH /api/api-keys に "agent"（null で解除）と "storage" を付けて送ります。サーバーでは chatwalaau keys set ID --agent hr-desk --storage temporary（--no-agent で解除）です。文書の相談窓口を参照してください。

v0.215.0 への更新

更新する。API_KEY / RESPONSES_API_KEY を使っていた呼び出し元は 401 になる。
必要なら API_KEYS_FILE を設定する（Azure App Service では /home の下）。
呼び出し元ごとにキーを作る。BFF や SDK のアプリには responses、CLI（CHATWALAAU_API_KEY）と自動化には api、キー管理が必要な場合だけ admin。
.env とプラットフォームの構成から API_KEY と RESPONSES_API_KEY を消す。

responses のキーは、RESPONSES_API_KEY と同じ保証を引き継ぎます。持ち主は API を呼べますが、その API を制限する設定（運用者向けの制御）は変更できません。ループバックからのリクエストはキーなしで /api/* を通るので、そうした呼び出し側は別のホストで動かしてください。

Web SPA 認証（任意）

ChatWalaʻau を、単一のオペレータがブラウザでサインインするプライベートなクラウド Web アプリとしてデプロイする場合に使います。API キー（CLI / SDK 用に残る）と共存し、 既定で無効です。AUTH_USERNAME を設定しなければ挙動は変わりません。

AUTH_USERNAME=admin
AUTH_PASSWORD_HASH=scrypt$N=16384,r=8,p=1$<base64-salt>$<base64-hash>
# AUTH_SESSION_TTL_SECONDS=86400     # 既定 24h、スライディング
# AUTH_COOKIE_SECURE=auto            # auto / true / false
# AUTH_COOKIE_NAME=chatwalaau_session
# AUTH_SESSION_PERSIST=true          # 再起動を跨いでセッションを維持（既定）
# AUTH_SESSION_STORE_PATH=.auth/session_tokens.json

ハッシュは同梱 CLI で生成します:

chatwalaau hash-password                              # 対話（2 回確認）
echo "$PASSWORD" | chatwalaau hash-password --stdin --quiet   # スクリプト

AUTH_USERNAME を設定すると SPA は /login を描画し、サーバは定数時間で資格情報を検証して不透明トークンを HttpOnly + SameSite=Strict Cookie で発行します。以降、バックエンドはすべての書き込みエンドポイントと AG-UI ストリームで、Bearer の API キー（スコープ api か admin） または有効なセッション Cookie のいずれかを受け付けます。/v1/responses は Bearer のみのままです。

追加の Python 依存なし（標準ライブラリの hashlib.scrypt + secrets）
単一ユーザー・単一プロセスモデル
非ループバックデプロイでは HTTPS を強く推奨
ループバックの CLI 呼び出しは無資格情報のバイパスを維持

セッションは再起動を生き延びます

v0.104.0 以降、サインインはバックエンドの再起動を生き延びます。デプロイ、クラッシュ、開発サーバの再起動のいずれでも、全ブラウザがログイン画面へ戻されることはありません。サーバが AUTH_SESSION_STORE_PATH に保存するのはセッショントークンの SHA-256 ダイジェストのみであり、トークン本体ではありません。したがってこのファイルが漏洩しても有効な Cookie を作ることはできず、暗号化も不要です。書き込みはアトミックで、POSIX では 0600、git 管理からも除外されます。

全セッションをサインアウトさせるには、運用に合う方法を選んでください。

操作	効果
`AUTH_SESSION_STORE_PATH` を削除	次回の再起動で全セッションが終了
`AUTH_PASSWORD_HASH` をローテーション	次回の再起動で全セッションが即時終了
`AUTH_SESSION_PERSIST=false`	従来の挙動（プロセスと共にセッションが消滅）に戻す

プロセスの再起動だけでは、もはやユーザーはサインアウトされません。

セッションが失効したとき

セッションが失効した場合（TTL 切れ、他所でのログアウト、パスワードのローテーション）、アプリは /login へ再読み込みしません。そのままのチャットの上にサインインダイアログ を開くので、入力中のメッセージ、添付、モデル選択はすべて保持されます。サインインすれば元の場所に戻ります。/login ページは初回読み込み時と明示的なサインアウト後に使われます。

同様に、送信時にサーバへ到達できなかった場合、メッセージは破棄されずに Retry ボタン付きで入力欄へ戻されます。

API キー​

キーを作る​

どこで何が受け付けられるか​

キーごとの上限​

キーごとのエージェントと会話​

v0.215.0 への更新​

Web SPA 認証（任意）​

セッションは再起動を生き延びます​

セッションが失効したとき​