エージェント向け API キー：read、write、publish の使い分けと、本当に見返す監査ログ

各エージェントには、その仕事に必要な範囲でいちばん狭い Shager のキーを渡してください。レポートには read、下書きには write、そして publish は投稿を予約するステップだけです。キーは環境変数か MCP クライアントの設定に保管し、プロンプトには絶対に入れません。取り消しとローテーションはエージェントダッシュボードで行い、エージェントのすべての呼び出しが記録される監査ログを読みます。新しいエージェントが落ち着くまでは、少なくとも週に1回は確認しましょう。

これが方針です。この記事の残りでは、その理由と仕組みを説明します。誰も理解していない方針は、不便に感じた最初の場面で無視されてしまうからです。

各スコープで何ができるのか

Shager のキーは、3つのスコープのうち1つ以上を持ちます。API の各オペレーションは必要なスコープを宣言しており、OpenAPI ドキュメントの各オペレーションにある x-scope で確認できます。MCP のツールは同じオペレーションなので、MCP 経由でも同じルールが適用されます。

スコープ	オペレーション
read	whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics
write	create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post
publish	schedule_post

この表で注目すべき点が2つあります。

1つ目は、publish に含まれるオペレーションが1つだけで、それがクライアントのアカウントにコンテンツを公開するものだという点です。これを切り離していることに意味があります。エージェントは、メディアのアップロードからアカウント別キャプションの下書き、承認リンクの送付まで、ほぼすべての作業をこなせますが、ページに投稿を載せることだけはできません。

2つ目は、cancel_post が write に含まれている点です。下書きを担当するエージェントでも、予約済みの投稿を下書きに戻せます。これは意図的な設計です。ミスを止めるほうが、ミスを犯すより簡単であるべきだからです。

必要なスコープを持たないキーで呼び出すと、標準形式 { "error": { "code", "message" } } のエラーが HTTP 403 で返ります。エージェントは別の抜け道を探すのではなく、そのエラーを報告すべきです。常設の指示にも、そう書いておきましょう。

横にスクロールすると図全体を表示できます

キーの入手経路

経路は2つあります。

人がキーを作成する。 app.shager.ai/dashboard/agents でスコープを選んで作成します。エージェンシーが既存のアカウントにエージェントを追加するときの、通常の方法です。

エージェントが自分で登録する。 アカウントを持たないエージェントは、agent_name と、できれば担当者の contact_email を付けて POST https://app.shager.ai/api/v1/agent/signup を呼びます。一度だけ表示される api_key と、claim_url が返ってきます。このキーはすぐにサンドボックスで使え、ワークスペースを5つまで作成し、メディアをアップロードし、下書きを作り、読み取りができます。予約や公開、クライアント向け接続リンクの作成、承認依頼の送信はできません。

curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'

これらの制限が解除されるのは、人が claim_url を開いてログインし、オーガニゼーションを引き継いだときだけです。その時点で、エージェントのキーに publish も付与するかどうかを人が決めます。誰も引き継がなければ、サンドボックスは7日後に期限切れになります。手順の全体は /auth.md で公開しており、詳しい流れはエージェントのセルフサインアップと引き継ぎで解説しています。

この設計の考え方はシンプルです。エージェントは自分で調べて準備まではできますが、実際のアカウントを接続して公開するときには、必ず人を通ります。

エージェントはキーをどう保管し、どう送るべきか

Shager のキーはベアラートークンで、Authorization: Bearer shgr_live_... として送ります。RFC 6750 にあるとおり、ベアラートークンの本質的な性質は、持っている者なら誰でも使えることです。ほかに身元を証明するものはありません。つまり、やるべきことは漏らさないこと、これに尽きます。

実際には次のようにします。

1. 環境変数に置き、設定から参照する。 Claude Code の MCP ドキュメントによると、.mcp.json のヘッダーでは ${VAR} の展開がサポートされています。ファイルはコミットしてもよく、キーは環境変数に残ります。
2. プロンプトには絶対に入れない。 チャットに貼り付けたキーは、会話履歴やログに残り、共有された会話に含まれてしまうこともあります。
3. クライアントのフォルダーにも入れない。 クライアントごとのコンテキスト用フォルダーを用意している場合、そこはキーを置く場所ではありません。そうしたフォルダーは共有されたり、zip で渡されたりします。
4. エージェントの役割ごとにキーを1つ。 レポートのジョブ、下書きのエージェント、予約のステップでキーを共有すべきではありません。1つが漏れても、取り消すのは1つで済みます。

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}

Shager の MCP サーバーは、この API キーのヘッダーを受け付けます。代わりに OAuth でログインして接続するクライアント（Claude や ChatGPT のカスタムコネクターなど）でも、同じように管理できます。接続は人が Shager の承認画面で許可し、公開は初期状態でオフの別のチェックボックスになっていて、接続は同じ監査ログに表示されます。ChatGPT での設定手順は Shager と ChatGPT で説明しています。

ダウンタイムなしのローテーション

キーは、アクセス権を持つ人が離れたとき、キーが漏れた可能性があるとき、そして継続できる定期的なスケジュールでローテーションすべきです。空白期間を生まない手順は次のとおりです。

1. ダッシュボードで、同じスコープの新しいキーを作成します。
2. エージェントが動いている環境の環境変数を更新します。
3. 新しいキーで whoami を実行し、動作することと、想定どおりのスコープが表示されることを確認します。
4. 古いキーを取り消します。

取り消しは、そのキーを使ったすべての呼び出しに、MCP と REST の区別なく適用されます。

横にスクロールすると図全体を表示できます

レート制限も安全の一部

キー1つあたりの上限は毎分120リクエストです。行儀のよいエージェントがこれに近づくことはありません。クライアント1社分の週次の下書き一式でも、呼び出しは数十回程度です。エージェントが HTTP 429 に当たるのは、たいていループに陥っている、つまり同じ失敗する呼び出しを何度もリトライしているときです。指示では 429 を「もっと速くリトライする理由」ではなく「止まる合図」として扱わせましょう。間隔を空け、報告し、人に確認してもらいます。

監査ログを読む

エージェントダッシュボードには、エージェントのすべての呼び出しの監査ログが表示されます。役に立つのは、誰かが読んだときだけです。新しいエージェントを入れて最初の数週間に確認すべき点は次のとおりです。

1. 想定外の呼び出し。 レポート用のエージェントが create_post を呼んでいたら、指示かキーのどちらかが間違っています。
2. ワークスペースのずれ。 作業の対象ではないクライアントに触れている呼び出しです。1つのエージェントで多数のクライアントを回すで取り上げている、クライアントを取り違えるミスの早期警告になります。
3. エラーの連続。 403 が繰り返されているなら、エージェントがスコープ外のことを試み続けています。直すべきはスコープではなく指示です。

問題のない状態が数週間続いたら、あとは週に1回ざっと目を通せば十分です。

よくある質問

エージェントに publish スコープを持たせてもよいのでしょうか？

下書きの質を信頼できるようになり、クライアント承認リンクか社内のレビュアーによるレビューのステップがあれば、持たせても構いません。うまくいくやり方の1つは、publish を別のキーにして、短いスクリプトで書いた予約ステップだけで使うことです。そうすれば、書くエージェントと公開するエージェントが分かれます。

サンドボックスが引き継がれると、エージェントのキーはどうなりますか？

オーガニゼーションは人のものになり、キーはその中で引き続き使えます。そのキーに予約と公開も許可するかどうかは、引き継ぎの時点で人が選びます。キーの取り消しや新規作成は、いつでもダッシュボードから行えます。

キーを1つのクライアントのワークスペースだけに限定できますか？

スコープが制限するのは、キーで何ができるかであって、どのワークスペースで操作できるかではありません。クライアントはワークスペース、クライアントごとのコンテキスト、そして書き込みの前に必ずワークスペースを名前で特定する習慣によって分けてください。そのうえで役割ごとに別のキーを使えば、取り消しが必要なときも影響を最小限に抑えられます。

次に読むもの

初めてエージェントをセットアップするなら、エージェント向けの入口でキーを入手する2つの方法を紹介しています。まずは write のキーから始め、下書きの質が十分だと判断できてから publish を追加しましょう。