認証とアクセス
API token、Agent API Endpoint、Thread visibility の連携を説明します。
このページの例は v1 の公開済み Agent API を使用します。harness の直接実行と任意のプリセットには、v2 クイックスタートを参照してください。
アプリケーションの API request には Project API key を使用します。
Authorization: Bearer msp_...
Content-Type: application/jsonキーの作成と保管
対象の Project settings → Project API keys でキーを作成します。秘密値は一度だけ表示され、サーバーにはハッシュのみ保存されます。信頼できる backend に保管し、ブラウザーやモバイルのクライアントコードには含めないでください。
一つの Project に複数のキーを作成できます。各キーは一つの Project にのみ属し、同じ Agent 設定、Session、ファイルのアクセス権を持ちます。キーごとの scope 設定はありません。Project key では account、Project、他のキーを管理できません。Provider と MCP の credential は別途設定します。
Agent API Endpoint へのアクセス
Public Thread API では引き続き公開済み Agent と live API endpoint version が必要です。キーが有効かつ未失効で、Agent と同じ Project に属する必要があります。Project owner と Agent owner も一致する必要があります。同じ account が複数の Project を所有していても、アプリケーションキーは Project を越えてアクセスできません。
未公開の Agent は 409 agent_not_published、live endpoint version がない場合は 409 service_inactive を返します。アクセス拒否は resource の境界に応じて 403 forbidden または 404 not_found になります。
ユーザーの識別と実行
backend がエンドユーザーを認証し、Thread 作成時に必須の opaque userId を渡します。mosoo は Thread、Run、ファイル、委任 MCP 呼び出しに不変の (Project, userId) context を保持しますが、エンドユーザーの認証は行いません。保存した Thread ID へのアクセス認可も backend の責任です。
Run は公開済み Agent 設定を使用します。Thread API request で provider credential、tool、runtime settings、Agent 設定を上書きすることはできません。
キーの更新と移行
同じ Project で新しいキーを作成し、連携設定を更新してから古いキーを失効させます。失効後の新規 request は拒否されますが、受理済みの処理は停止せず、Thread も削除されません。同じ Project の別の有効なキー、または Project owner が既存の Thread を操作できます。
旧 mst_ と grt_pat_ token は拒否され、default Project に自動で割り当てられることはありません。対象 Project ごとにキーを作成し、連携先の credential を更新してください。CLI ユーザーは現在の CLI で再ログインが必要です。ブラウザーと CLI のログインは account control plane へのアクセスを提供し、CLI credential は別の mcli_ prefix を使用します。Project key は account ログインの代わりにはなりません。
安全な再試行
同じ操作と request body の再試行には同じ Idempotency-Key を使用します。Project のキーは冪等性記録と rate limit を共有するため、キーを更新しても処理は重複せず、制限もリセットされません。同じ Project の異なる連携には別の操作 ID を使用してください。
同じ key と request では元の response が返ります。処理中、または異なる body に同じ key を使用すると 409 idempotency_conflict が返ります。