メインコンテンツまでスキップ

パートナーアプリ向け OAuth

MonoChat ユーザーのために動くパートナーアプリ、自動化ツール、カスタムアプリは、API トークンの代わりに OAuth アクセストークンでカスタム関数 API(POST https://app.monochat.ai/api/<slug>/custom-functions/<path>)を呼び出せます。ユーザーは MonoChat のページでアプリを承認し、アクセスできる組織を選び、プロフィール設定の 連携アプリ からいつでも取り消せます。

API トークンは同じエンドポイントで引き続き使えます。OAuth は他の人のために動くアプリ向けの方法です。アプリはパスワードや API トークンを見ることがなく、各ユーザーが自分で接続を切れます。

アプリはユーザーとして動作します

アクセストークンによる呼び出しは、アプリを承認したユーザーとして、そのユーザーのロールで実行されます。実行できるのは組織のカスタムメソッドだけで、ユーザーがエージェントである組織に限られます。

クライアントを取得する​

アプリ用のクライアントを MonoChat に依頼してください。MonoChat は次の内容で登録します。

  • 承認ページと 連携アプリ に表示されるアプリ名
  • 完全一致で照合されるリダイレクト URI:https のアドレス、または localhost、127.0.0.1、[::1] 上の http(任意のポート)
  • 要求できるスコープ:この API では custom-functions:run

クライアント ID(monochat_rc_ で始まる)と クライアントシークレット(monochat_cs_ で始まる)が発行されます。シークレットは一度しか表示されず、MonoChat はそのハッシュだけを保存します。シークレットはサーバーに保管し、ブラウザやモバイルアプリには置かないでください。

ブラウザやユーザーのコンピューター上で動くアプリなど、シークレットを守れないアプリは、MCP クライアントと同じようにクライアント ID メタデータドキュメントの URL をクライアント ID として使えます。その場合、シークレットは送りません。

エンドポイント​

https://app.monochat.ai/.well-known/oauth-authorization-server の認可サーバーメタデータにすべてのエンドポイントが記載されています。ホワイトラベルやセルフホストの環境では、その環境のアドレスを使ってください。

設定値
認可エンドポイントhttps://app.monochat.ai/oauth/authorize
トークンエンドポイントhttps://app.monochat.ai/oauth/token
取り消しエンドポイントhttps://app.monochat.ai/oauth/revoke
リソースhttps://app.monochat.ai/api/custom-functions
スコープcustom-functions:run
クライアント認証HTTP Basic、またはリクエスト本文の client_id と client_secret

リソース自体のメタデータは https://app.monochat.ai/.well-known/oauth-protected-resource/api/custom-functions にあります。

ユーザーを接続する​

MonoChat は PKCE(S256)付きの認可コードフローを使います。ユーザーは 2 段階認証(メールまたは認証アプリ)を設定しておく必要があります。

  1. response_type=code、client_id、登録済みの redirect_uri、scope=custom-functions:run、resource=https://app.monochat.ai/api/custom-functions、state、code_challenge_method=S256 付きの code_challenge を指定して、ユーザーを認可エンドポイントに送ります。
  2. 必要に応じてユーザーが MonoChat にサインインします。承認ページにはアプリ名と あなたに代わってカスタムメソッドを実行 が表示されます。ユーザーはアプリがアクセスできる 組織 を選び(選ばない場合はすべて)、6 桁の確認コードを入力して 許可 をクリックします。
  3. MonoChat は code、state、iss を付けてユーザーを redirect_uri に戻します。ユーザーが 拒否 をクリックした場合は、代わりに error=access_denied が送られます。
  4. 5 分以内にトークンエンドポイントでコードを交換します。
curl -X POST https://app.monochat.ai/oauth/token \
-u "<client_id>:<client_secret>" \
-d grant_type=authorization_code \
-d code=<code> \
-d redirect_uri=<redirect_uri> \
-d code_verifier=<code_verifier>

応答には、expires_in 秒(1 時間)有効な access_token(monochat_at_ で始まる)、refresh_token(monochat_rt_ で始まる)、付与された scope が含まれます。

API を呼び出す​

アクセストークンを Bearer トークンとして送ります。

curl -X POST https://app.monochat.ai/api/<slug>/custom-functions/<path> \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
ステータス条件
401トークンが不明、期限切れ、取り消し済み、または MCP サーバーなど別のリソース向けに発行されたものです。WWW-Authenticate ヘッダーがリソースのメタデータを示します。
403組織がユーザーがアプリに許可した組織に含まれていない、ユーザーがその組織にアクセスできない、または許可に custom-functions:run が含まれていません。
429上限に達しました。Retry-After の秒数だけ待ってください。呼び出しは 1 分ごとに数えられます。許可ごとに 120 回、クライアントごとに 1,200 回で、このエンドポイントに対する組織自身の上限も適用されます。

更新と取り消し​

  • **更新:**アクセストークンの期限が切れる前に、grant_type=refresh_token と refresh_token でトークンエンドポイントを呼び出します。更新のたびに新しいリフレッシュトークンが返るので、新しいものを使ってください。置き換えられてから 1 分以上経って再利用されたリフレッシュトークンは、許可を終了させます。
  • **有効期限:**許可は、最後の更新から 90 日後、ユーザーが 連携アプリ で取り消したとき、またはユーザーがパスワードを変更・リセットしたときに終了します。その後、ユーザーはアプリを再度承認する必要があります。
  • **取り消し:**ユーザーの接続を切るには、クライアント認証を付けてアクセストークンまたはリフレッシュトークンを取り消しエンドポイントに送ります。
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

同じユーザーをもう一度アプリに接続すると、以前の許可が置き換えられます。