/v1 的 API origin。
应用目录
GET /v1/applications 返回 200、{applications,oauth_clients}。应用项包含 id/name/category、credential_url、oauth 支持布尔值、credential_fields、verification_may_charge、evidence 和 operations。操作项包含 name、description、write、input_schema、required_scopes。Evidence 表示声明的实现/验证范围,不是你的账户实时就绪状态。
OAuth_clients 包含 provider、client_id、redirect_uri、updated_at,不包含 client_secret,无分页契约。
配置 OAuth 客户端
PUT /v1/applications/{provider}/oauth-client 接受严格 client_id(1–2000 字符)、client_secret(1–32,768 字符)、redirect_uri。Redirect 路径必须恰为 /oauth/callback,不含用户名、密码、query、fragment;要求 HTTPS,但允许 HTTP loopback 主机 127.0.0.1、localhost、[::1]。必须与 Provider 注册的回调一致。
将真实值保存在私有 oauth-client.json,不放入 shell 历史:
{configured:true,provider,client_id,redirect_uri}。配置插入或替换租户/Provider 客户端,加密保存 Secret,不完成用户同意。不支持的 Provider 返回 400 app_oauth_unsupported,严格输入无效为 400 invalid_request。配置变化会使进行中 flow 的 client_updated_at 检查不匹配;client ID 变化可能要求已有授权重新认证。重复配置不是保留 flow 的无副作用操作。
发起同意流程
POST /v1/connections/{id}/authorize 无必需请求体,返回 200、{id,authorization_url,expires_in:600}。保存 flow ID,再由目标用户打开 URL;其中含 state,应私有处理。创建 flow 不会自动代替用户同意。
404 connection_not_found;不支持 OAuth 为 400;未配置为 409 app_oauth_setup_required。
新 flow 会取消同一连接已有 pending flows,没有幂等键;自动重试 POST 可能使已经展示给用户的 URL 失效。Flow 固定连接版本与客户端 updated_at,保存随机 state 摘要和加密 verifier,在 Provider 定义支持时使用 PKCE。请求 scope 来自已选择的应用操作/配置。
查询或取消 flow
GET /v1/authorization-flows/{id} 返回 200、{id,connection_id,status,error_code,expires_at}。状态包括 pending/completed/failed/cancelled/expired。超过截止时间的 pending 在读取时显示 expired,此投影本身不持久化过期转换。未知或其他租户 flow 返回 404 app_oauth_flow_not_found。
/oauth/callback,不要发送 owner Token 或手工重放授权码。回调检查 state、到期、连接版本和客户端配置,兑换 code 并验证账户/scope。成功保存 OAuth 封装、清除 managed Secret 关联、递增连接版本、设为 ready/enabled、完成 flow。与普通连接验证不同,成功回调会显式启用连接。
拒绝同意记录 failed/app_oauth_denied,其他已捕获回调失败记录 failed/app_oauth_failed;无效或复用 state 可返回 400 app_oauth_state_invalid。失败兑换也可能将浏览器送回 Console,因此重定向不证明成功,应轮询 flow 并检查连接最终状态。
检查连接授权
GET /v1/connections/{id}/authorization 返回 200,包含 connection_id、authentication、provider_revoked:false、state、refresh_available、可空 expires_at。它读取保存的凭据生命周期,不实时检查 Provider 撤销。连接不存在为 404,非 Tool 为 400 connection_kind_mismatch。
Refresh_available 只说明存有 refresh token,不证明重放安全;状态查询不执行 refresh。未知 refresh 结果不能盲重放可能已轮换的 token,应进入重新授权流程。删除本地 Tool 凭据使用断开连接,明确返回 provider_revoked:false。Flow 取消和断开都不承诺 Provider 侧撤销。
来源:OAuth 实现、应用目录、HTTP 路由。本轮没有修改 OAuth 客户端、同意、Token 兑换或外部账户。下一步:应用集成、HTTP 总览。