認証

API key の形式

VoiceAgent API keys は vak_ で始まる secret string です。値全体を password と同じように扱ってください。secret manager または environment variable に保存し、 browser code、mobile apps、logs、source control には保存しないでください。

key の取得場所

Workspace admins は Dashboard の /api-keys で API keys を作成できます。 作成時に secret をコピーしてください。その後は連携環境に secret だけを保存します。

リクエストヘッダー

API は同等の 2 種類のヘッダー形式を受け付けます。

Authorization: Bearer vak_...
X-API-Key: vak_...

1 回のリクエストではどちらか 1 つのヘッダーを使用してください。 Authorization に vak_ token が含まれている場合、VoiceAgent は X-API-Key を確認する前にその token を検証します。

ローテーション

key rotation は #42 の Phase 5 hardening work の一部として計画されています。rotation tooling が利用可能になるまでは、replacement key を作成し、連携にデプロイして、traffic を確認したうえで、 Dashboard から古い key を revoke してください。

スコープ

Public routes は API key scopes を強制します。Integration に必要な最小の concrete scopes を選び、high-risk grants は automated systems で使う前に review してください。

Canonical scope list、wildcard policy、OpenAPI metadata fields については スコープリファレンス を参照してください。

認証失敗

API key がない、無効、または期限切れの場合は、標準の error envelope とともに 401 Unauthorized が返されます。

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}