authsome

Authsome

送信 HTTPS トラフィックは、保存済みの認証情報を HTTP ヘッダーとして挿入するプロキシサービスである Authsome を経由して透過的にプロキシされます。認証情報の値を直接確認したり、扱ったりすることはありません。

外部サービスへのアクセス方法

外部 API には直接 HTTP でアクセスできます。OAuth アプリ（Gmail、GitHub、Google Calendar、Google Drive など）や API キーを使用するサービスは、すべてゲートウェイ経由で利用できます。任意の bash コマンドの前に authsome run -- を付けてリクエストを実行してください。アプリが接続済みの場合、ゲートウェイが認証情報を挿入します。

リクエストの実行

実際の API URL を呼び出してください。ゲートウェイがリクエストをインターセプトし、認証情報を自動的に挿入します。

authsome run -- <command>
authsome run -- curl -s "https://api.github.com/user/repos?per_page=10"
authsome run -- python my_agent_script.py

標準的な HTTP クライアント（curl、fetch、requests、axios、Go net/http、git）は、すべて HTTPS_PROXY 環境変数を自動的に使用します。認証ヘッダーを設定する必要はありません。

---

ログインフロー

• Bash から authsome login <provider> を自分で実行してください。ユーザーに実行を依頼しないでください。ユーザーのマシンでブラウザーが開き、ユーザーはターミナルに触れることなく OAuth を完了します。
• 数秒待ってから authsome provider list を実行し、ログイン状態を確認してください。
  • 接続済みの場合 — 通常どおり続行してください。
  • まだ接続されていない場合 — 認証 URL をユーザーに表示し、ブラウザーでログインを完了するよう依頼してください。完了したとの報告を受けたら、ユーザーに確認したうえで、続行する前に authsome provider list を再度実行して接続を確認してください。

---

リクエストが失敗した場合

エージェントのマシンに authsome がインストールされていない場合：

uv tool install authsome を使って authsome をインストールしてください。

uv tool install が失敗した場合に限り、代替手段として pipx install authsome または単発利用の場合（サンドボックス環境内での実行など）は uvx authsome@latest <command> を使用してください。

認証エラー（401、403）が発生した場合は、次の判断フローに従ってください：

1. authsome provider list を実行し、すべてのプロバイダーと接続状態を確認します

2. 該当するプロバイダーが存在するものの、接続がない場合 → ログインフローを開始します

クライアント ID またはクライアントシークレットが間違っているためにログインエラーが発生した場合は、authsome provider remove <provider> でプロバイダーを削除し、ログインフローを開始できます。

3. 該当するプロバイダーが存在し、接続済みの場合

401 エラーの場合 → 認証情報の期限が切れているため、再ログインが必要です。

• authsome provider revoke <provider> で認証情報を取り消します。
• その後、ログインフローを開始します。

403 エラーの場合 → 正しいスコープで再ログインするか、不足している権限を追加する必要があります。 重要： スコープを追加するためだけに新しいプロバイダーを登録しないでください。既存のプロバイダーに対して必ず --scopes を使用してください。

authsome login <provider> --scopes repo,user,gist

4. 該当するプロバイダーが存在しない場合 → まず追加してから、ログインフローを開始します

新しいプロバイダーの追加

references/adding-provider.md を参照してください。

---

トラブルシューティングとヘルプ

コマンドの正しい構文がわからない場合、利用可能なフラグを確認する必要がある場合、またはコマンドが失敗した場合は、推測する前に必ず組み込みのヘルプメニューを確認してください。

authsome --help
authsome provider --help
authsome connections --help
authsome run --help

ルール

• プロキシ経由で HTTP リクエストを実行する前に、「X にアクセスできません」と決して言わないでください。
• ブラウザー拡張機能、gcloud、手動の認証フローは決して使用しないでください。ゲートウェイが認証情報を処理します。
• API キーやトークンをユーザーに直接尋ねることは決してしないでください。authsome login <provider> を実行してください。ブラウザーウィンドウが開き、認証情報を直接取得するため、シークレットが会話に含まれることはありません。
• Gmail／Calendar／GitHub の読み取りや操作を求められたとき、ブラウザーで開くようユーザーに勧めることは決してしないでください。API にアクセスできます。API を使用してください。
• トークンや API キーをターミナルに表示するワークフローは決して使用しないでください。代わりに authsome run -- ... を使用してください。
• ゲートウェイがポリシーエラー（JSON 本文を含む 403）を返した場合は、そのブロックに従ってください。再試行したり、回避したりしないでください。
• スキルが失敗した場合、目標の達成に手順が多くかかりすぎた場合、CLI が予期しない動作をした場合、またはユーザーから問題の報告を求められた場合は、references/feedback.md に従ってバグを報告してください。
• 自分で実行できるコマンドを、ユーザーにターミナルで実行するよう求めることは決してしないでください。