API

認証

ワークスペースキーでMandavo APIに認証し、そこからスコープ限定エージェント認証情報を鋳造する。

ワークスペースキー

アイデンティティの作成、ポリシーの記述、認証情報の発行といった管理呼び出しは、ワークスペースキーで認証する。Settingsで生成し、Authorizationヘッダーにベアラートークンとして送る。

ワークスペースキーはあなたのバックエンド専用だ。エージェントに渡ることは決してなく、エージェントはあなたが鋳造する短期認証情報で行動する。

すべてのリクエストは https://api.mandavo.com へ送られ、/v1 から始まるパスプレフィックスでバージョン管理される。破壊的変更は新しいプレフィックスの下で出荷され、追加的変更はそうではない。

リクエストとレスポンスはJSONだ。ボディを伴うリクエストには Content-Type: application/json を送ること。

エージェントに行動させるには、発行エンジンを通じてワークスペースキーをスコープ限定認証情報と交換し、その短期トークンだけをエージェントに渡す。トークンはアイデンティティ、スコープ、失効期限を伴う。

エージェント認証情報は単一タスク・メモリ上のものとして扱うこと。永続化せず、次のタスクには新しいものを要求すること。

APIは標準的なHTTPステータスコードを使用する。401はキーが欠落または無効であることを、403はアクションが呼び出し元のスコープ外であるかポリシーによって拒否されたことを、429はレート制限中であることを意味する。エラーボディには機械可読なコードと人間可読なメッセージが含まれる。