API 参考 / feishu-integrations

飞书 OAuth 身份绑定回调

GET /api/v1/integrations/feishu/identity/callback · handleFeishuIdentityCallback

飞书 OAuth 授权成功后的浏览器回调端点。验证 state 防 CSRF，用 code 换 open_id/union_id 与用户展示资料，落库 user_feishu_identities。不走 session/PAT 鉴权——用户 ID 从 state 恢复。 integrationId 也从 state 恢复，因此该 URL 是全站固定值，可直接配置到飞书开发者后台的重定向 URL 白名单。state 伪造或过期、用户取消授权或换码失败时，返回品牌化失败结果页 text/html（无反射注入、无开放重定向），并向父页面广播失败信号让其提示重新绑定。沿 handleFeishuIntegrationEvent 公开端点范式（security: []）。成功时返回自动通知父页面刷新并关闭当前窗口的 text/html；secret/token/code 绝不落库或进日志。

公开端点，无需鉴权。

参数

code: string
state: string
error: string —— 飞书在用户取消授权时回传的 OAuth 错误码（如 access_denied）；据此渲染「你取消了授权」失败页。

响应字段 · 200

ok（必填）: boolean
challenge: string —— URL verification challenge；普通事件处理时为空。

错误

401：Problem 错误响应
404：Problem 错误响应

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/integrations/feishu/identity/callback?code=…&state=…"

响应示例

HTTP/1.1 200
{
  "ok": true,
  "challenge": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引