跳到主要内容

合作伙伴应用的 OAuth

为 MonoChat 用户工作的合作伙伴应用、自动化工具或自定义应用,可以使用 OAuth 访问令牌而不是 API 令牌来调用自定义函数 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)的授权码流程。用户需要已设置两步验证(通过电子邮件或身份验证器应用)。

  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 秒(一小时)的 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 中的秒数。调用按分钟计数:每个授权 120 次,每个客户端 1,200 次,此外还有组织自身对此端点的限制。

刷新与撤销​

  • **刷新:**在访问令牌过期前,用 grant_type=refresh_token 和 refresh_token 调用令牌端点。每次刷新都会返回新的刷新令牌,请使用新的。被替换超过一分钟后再次使用的刷新令牌会终止授权。
  • **过期:**授权在最后一次刷新 90 天后、用户在 已连接的应用 中撤销时,或用户更改或重置密码时结束。之后用户需要再次批准该应用。
  • **撤销:**要断开某个用户,请携带客户端认证,将访问令牌或刷新令牌发送到撤销端点:
curl -X POST https://app.monochat.ai/oauth/revoke \
-u "<client_id>:<client_secret>" \
-d token=<refresh_token>

再次将同一用户连接到您的应用会替换其之前的授权。