本文へ移動

ドキュメント

OpenConnector の認証情報、Runtime Token、OAuth

セルフホストした OpenConnector の認証情報、runtime アクセス、OAuth コールバック、名前付き接続を設定します。

保守：OOMOL·

ソース確認日：2026-09-09. 例はリンク先のソースリビジョンと照合済みです。実際の外部 API の検証を示すものではなく、稼働中のバージョンとは異なる場合があります。

runtime アクセスとアプリの認証情報

管理者の認証情報はコンソールと /api を保護します。Runtime Token は /v1 と /mcp のクライアントを認可します。アプリの認証情報は接続したアカウントに属し、runtime 内に保持されます。これらは相互に代用できません。

自分の OAuth アプリを登録

セルフホストでは、サービス側で OAuth アプリを登録し、/api/oauth/configs の expectedRedirectUri を正確にコピーします。リモートのコールバックを設定する前に、OOMOL_CONNECT_ORIGIN を公開オリジンに設定し、必要なスコープを選んでください。

使用するアカウント接続を選ぶ

エイリアスを指定しない呼び出しは既定の接続を使います。名前付き接続は x-oo-connector-alias で選択できます。Runtime Token の接続許可により、使えるアカウントが制限される場合があります。

認証情報を永続化して保護

Docker イメージはローカルデータに /app/data を使用します。永続ボリュームをマウントしてください。保存する認証情報には OOMOL_CONNECT_ENCRYPTION_KEY を設定し、復元に必要な鍵を保管します。外部公開前にデプロイガイドを確認してください。

OAuth 接続を完了する

  1. まず OOMOL_CONNECT_ORIGIN をブラウザーで使うアドレスに設定します。/api/oauth/configs を読み、対象プロバイダーの expectedRedirectUri を OAuth アプリへ正確に登録します。管理者認証が有効な場合は管理者 Bearer トークンを付けてください。
  2. ローカルコンソールで OAuth の Client ID と Secret を保存します。必要に応じてプロバイダーが宣言する scopes の一部を選び、認証を開始してブラウザーでアクセスを許可します。
  3. コールバック後に /api/connections を確認し、アカウントと接続名を確かめてから Action を実行します。名前付き接続は事前に作成する必要があり、別名の指定だけでは作成されません。

次の最初のリクエストは管理者トークンで接続を確認します。次のリクエストはランタイムトークンと既存の work 接続で読み取り専用 Action を呼び出します。接続名は自分のものに置き換え、既定の接続を使う場合は別名ヘッダーを省略してください。

GET /api/connections
curl -s http://localhost:3000/api/connections \
  -H "Authorization: Bearer $OOMOL_CONNECT_ADMIN_TOKEN"
HTTP · GitHub
curl -s -X POST \
  http://localhost:3000/v1/actions/github.get_current_user \
  -H "Authorization: Bearer $OOMOL_CONNECT_RUNTIME_TOKEN" \
  -H 'x-oo-connector-alias: work' \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

結果の読み方

HTTP ランタイムの応答には success、message、data、meta が含まれます。HTTP ステータスだけでなく success と Action の出力スキーマを確認してください。実行メタデータに executionId があれば、対応するマスキング済みログを探せます。以下は応答形式の例であり、実際の API 実行結果ではありません。

応答形式の例
{
  "success": true,
  "message": "OK",
  "data": {},
  "meta": {}
}

呼び出しに失敗した場合

  • 認証エラーではエンドポイントと認証情報の種類を確認します。管理者認証は /api、ランタイム Bearer トークンは /v1 と /mcp 用です。プロバイダーの API キーをランタイムトークンの代わりには使えません。
  • 権限エラーでは Action の必要 scopes、ランタイムの Action ルール、接続へのアクセス権を確認します。有効なトークンでも指定アカウントを使えない場合があります。
  • 結果が空の場合は接続アカウントと対象リソースの共有範囲を確認します。認証に成功しても、すべてのワークスペース、チャンネル、文書へアクセスできるわけではありません。
  • 再試行前にエラーと実行ログを確認します。データを変更する Action はすでに完了していないか確認し、無条件に同じリクエストを繰り返さないでください。
Markdown で読む