统一身份与开放API：让蜂巢与其它系统协作

这两页都用于系统间对接，方向却不同：“统一身份”让业务系统确认正在访问的蜂巢员工是谁；“开放API”让外部程序以指定员工身份向蜂巢提交任务。管理员先明确方向，才能把正确的地址和凭据交给正确的维护人员。

本章需要平台管理员账号。创建或修改真实业务客户端、配置回调和发放API Key会影响系统间访问，应在已确认的对接范围内进行。本文不会展示真实Secret或Key。

先判断要实现哪种协作

场景	应使用什么	管理员要准备的内容
员工进入业务系统的账号管理页，业务系统需要确认员工身份	统一身份的网页登录	准确回调地址、客户端ID、客户端Secret、身份服务地址
Skill、面板或蜂巢身份MCP访问业务接口，网关需要确认当前员工	统一身份的业务Token校验	业务后端客户端认证和在线Token查询；仍由业务系统检查权限
业务后台、定时程序或其它应用希望让蜂巢分析数据并返回结果	开放API	固定绑定员工、执行引擎和业务范围的API Key

Token是短期访问票据；Secret和API Key是需要安全保存的秘密。它们的用途不同，不能互相代替。业务系统客户端Secret放在业务后端，开放API Key放在调用蜂巢的程序后端，二者都不应写进浏览器页面、Skill文件、截图或普通日志。

统一身份为什么不代替业务账号和权限

蜂巢能证明“这是员工张三，正在访问照明系统”，但照明系统还要决定张三对应哪个业务账号，以及能看哪些项目、执行哪些操作。因此，在蜂巢启用一个客户端，只完成蜂巢一侧的配置，不代表业务账号关联、接口调用或权限检查已经完成。

统一身份提供两个配合使用的过程：

网页登录确认身份。业务后端通过OIDC授权码流程和PKCE确认员工身份，再在自己的账号页面处理关联。OIDC是一套标准登录协议，PKCE用于核对发起和兑换授权结果的请求是否属于同一次登录。
业务接口逐次验票。Skill、面板或MCP请求业务接口时携带短期业务Token；业务网关使用客户端认证向蜂巢在线查询，核对是否有效、是否由本平台签发、是否发给当前目标系统，再检查自己的业务权限。

业务Token固定有效期5分钟，每次业务请求都应在线校验。网页登录中的ID Token、身份访问Token与业务Token用途不同，对接方不能混用。

查看哪些系统已配置客户端

打开左侧“集成与接入→统一身份”，默认进入“接入管理”。

页面上方列出业务系统数、已配置客户端数和可签发身份数。只有业务系统与客户端都启用，才计入“可签发身份”。下面的列表按系统显示客户端ID、接入状态和维护人；可以搜索系统名称、标识或客户端ID，也可以按状态筛选。

接入状态	含义	下一步
未配置客户端	此系统还没有身份客户端	点击“配置接入”准备创建
客户端已停用	客户端存在，但不允许使用蜂巢身份	核对停用原因与业务后端准备情况
系统已停用	业务系统被停用	到“业务系统”核对状态；单独启用客户端无效
客户端已启用	蜂巢一侧允许此客户端使用身份	继续验证业务账号关联和业务请求

没有业务系统时，点击“前往业务系统”先登记。一个业务系统对应一个身份客户端，不能在此页为同一系统创建多个独立客户端。

创建客户端

先请业务后端维护人员给出准确的回调地址。回调地址是业务后端接收登录授权结果的入口，必须与实际部署地址精确匹配。它与员工打开的“账号管理页面”可能不同，不能凭页面首页地址猜测。

在目标系统行点击“配置接入”。
填写可选的“账号管理页面”，这是员工管理业务账号关联的页面，可暂不配置。
在“准确回调地址”中每行填写一个完整HTTP或HTTPS地址，至少1个、最多10个，不能重复。
根据已确认的接入安排设置“启用客户端”。
点击“创建客户端”。
创建成功后立即复制客户端ID、新Secret和连接信息，交由业务后端维护人员安全保存。

回调和账号管理地址不支持通配符，不能包含用户名、密码、查询参数或片段。客户端只支持保密后端接入，不能让浏览器直接持有Secret。

新Secret只在创建或重置后这一次显示，关闭抽屉后无法再次查询。在“新Secret仅此次显示”区域使用“复制Secret”，确认安全保存后点击“已保存，隐藏”或关闭抽屉。显示新Secret时，保存与重置按钮会暂时禁用，避免在还没保管好秘密时重复操作。

成功后列表应出现客户端ID，并显示相符的启用状态。之后应由业务后端完成登录与验票对接，再使用获准员工账号验证；列表状态正常只是这一步的起点。

修改回调、账号管理页或启停客户端

在目标行点击“配置”。
修改账号管理页、回调地址或“启用客户端”开关。
点击“保存配置”，阅读影响后点击“确认保存”。
看到“接入配置已保存。”后，核对列表状态并重新验证业务登录。

现有客户端配置发生变化，会使该客户端已有的在线授权失效，员工需要重新登录业务账号管理页。请在业务后端已准备好对应地址时修改回调，避免新旧地址不同造成登录失败。

如果业务系统已停用，抽屉会提示“业务系统已停用，即使启用客户端也不能签发身份”。需要恢复系统时，从“业务系统”详情处理系统状态。

重置Secret

Secret丢失或需要更换时，无法查看旧值，只能重置。

打开目标客户端的“配置”。
点击抽屉底部“重置Secret”。
阅读“旧Secret和该客户端现有在线授权将立即失效”的提示，确认业务后端能够同步更新后，点击“确认重置”。
立即复制并安全保存新Secret，更新业务后端配置。
完成后重新验证网页登录和业务验票。

重置保持原客户端ID，旧Secret立即失效，不能把新旧Secret作为一段时间内同时可用的凭据。若配置已保存但刷新失败，先保存已经显示的新Secret，再关闭并重新打开抽屉；不要直接用旧页面再次提交。

把接入信息交给业务后端

选择“接入说明”，可以看到平台配置的“签发者”“发现地址”和“业务Token查询地址”。签发者用于判断身份来自哪个平台，发现地址供对接程序读取身份服务信息，查询地址用于业务接口在线验票。

可以逐项点击“复制”，也可以点击“复制接入信息”复制地址和接入要点。这些地址以蜂巢服务端配置为准，不要把本地前端调试地址当作身份签发地址。页面尚未登记任何业务系统时，需要先登记至少一个系统，才能读取这些地址。

交接后请共同检查：网页登录使用授权码和PKCE S256，范围为openid profile；修改业务账号关联前通过userinfo复查身份；业务请求逐次检查Token有效性、签发者和目标系统。控制台没有“一键完成联调”或替业务系统维护账号关联的按钮。

开放API为什么要绑定员工

蜂巢执行任务时要使用某个员工的工作空间、模型与业务能力。如果外部程序可以随请求任意换员工，就难以判断任务是谁发起、能够访问什么。开放API Key把员工、执行引擎和业务范围固定下来，让外部调用有明确身份和范围。

执行引擎是负责运行智能体任务的软件，当前可选Hive Pi和OpenCode；它与具体模型是两件事。业务范围分“综合范围”和指定业务系统范围，用来限定任务上下文；创建Key不自动增加绑定员工在业务系统中的资格或权限。

查询现有Key

打开“集成与接入→开放API”，默认显示“API Key”。

可以按名称、绑定员工、执行引擎、业务范围和状态组合查询，点击“查询”应用；“重置”清空条件。“刷新”同时重新读取Key与可选员工、业务系统，每页30项。

列表只显示Key的部分提示字符，完整Key不能从列表再次查看。“可用”表示Key没有撤销且员工当前可用；“员工已停用”表示调用身份不可用；“已撤销”表示此Key不再接受调用。

创建Key

准备一个可用的普通员工账号，确认他已有执行任务需要的能力与系统资格，并决定使用哪个引擎、哪个业务范围。

点击“创建Key”。
在“绑定员工”选择实际执行任务的员工。
填写“名称”，让后续管理员能识别用途，例如“照明日报后台”。
按需要填写“任务时限（分钟，留空跟随平台）”，允许1—120的整数分钟。时限包含排队与执行时间。
在“智能体”中选择Hive Pi或OpenCode。
在“会话业务范围”中选择“综合范围”或一个当前启用的业务系统。
点击“创建并显示Key”。
立即点击“复制”并安全保存完整Key，再点击“完成”。

成功后列表应出现此Key的名称、绑定员工、引擎和范围。完整Key只显示一次，关闭后无法再次查看。若丢失，应新建Key并更新调用方，再撤销旧Key。页面没有修改现有Key的员工、引擎、范围或名称的入口；需要改变绑定关系时，同样创建替代Key。

“创建Key”不可用时，先检查是否存在可用普通员工，以及页面是否提示员工或业务范围读取失败；使用“刷新”重新读取。创建Key不会自动发送示例请求。

调整任务时限

某个集成的任务稳定需要更长时间时，可在对应Key行点击“时限”。输入1—120之间的整数分钟，或点击“跟随平台”清空自定义值，然后点击“保存”。

成功提示为“时限已保存，仅影响新任务。”。它不会延长已经创建任务的截止时间；时限从排队开始计算，不能只按模型生成正文的时间估算。

撤销Key和更换Key

不用的调用方、错误发放或需要更换的Key，可在对应行点击“撤销”，核对影响后点击“确认撤销API Key”。成功后状态变为“已撤销”。

撤销会阻止新调用，以及使用此Key继续查询或取消异步任务；不会中断已经创建的任务。所以更换时应先创建新Key、更新调用方并验证，再撤销旧Key。不要依靠撤销Key来取消一个正在执行的任务。

给外部程序选择合适的调用方式

在“开放API→接入说明”中，三种模式都有可复制的请求示例。点击模式按钮切换，再点击“复制示例”；复制只取得文本，不会自动发送请求。由调用方把API_KEY和RUN_ID替换成实际值。

模式	适合什么情况	断开连接后的影响
异步长任务	分析时间较长、调用方需要提交后稍后查询	连接断开不会取消任务
普通响应	调用方可以一直保持连接，等待最后一次返回完整结果	客户端断开会请求取消任务
流式响应	调用方需要逐步接收正文、思考和工具活动	客户端断开会请求取消任务

流式响应使用SSE，即服务端通过一条持续连接逐步推送事件。它要求调用方正确处理事件和连接状态；控制台提供示例，不提供一个在线运行和调试外部请求的按钮。

异步任务的一次完整调用

调用方使用Key向/api/open/v1/runs提交任务，同时传入Idempotency-Key。
保存返回的任务编号，以后用同一Key查询/api/open/v1/runs/<RUN_ID>。
根据返回的run_status和terminal_reason判断任务是否成功、失败、超时或取消；HTTP返回200只代表查询请求成功。
需要取消时，调用/api/open/v1/runs/<RUN_ID>/cancel。返回202表示取消请求已登记，实际是否停止仍以查询结果为准。

Idempotency-Key叫幂等标识，用来把网络重试识别为“同一次提交”。例如提交后网络断开，不确定服务器是否收到，应使用同一个标识和相同输入重试，避免多创建一个任务。不能把同一标识用于不同输入；输入不一致会发生冲突。

请求中的model: hive-agent表示使用默认模型；也可以指定此Key绑定引擎已经开放的模型目录ID。它不是调用方任意更换员工或引擎的入口。

按响应处理失败

响应或现象	含义和处理
401	Key无效、已撤销，或绑定员工已停用。核对凭据、Key状态与员工状态
400或409	参数不正确，或重复提交的输入冲突。核对请求格式、业务范围和幂等标识
429	员工等待任务数量已经达到上限。查看该员工任务，处理后再提交
504	同步任务超时，或异步提交等待超时。异步接口返回504不表示任务停止，应以原幂等标识和相同输入重试，再查询任务
查询返回200，但没有成功结果	检查`run_status`和`terminal_reason`，不要把HTTP成功当作任务成功
取消返回202，任务仍在运行	取消请求已登记；继续查询最终状态
页面示例地址在实际调用方不可访问	示例按当前打开页面的地址生成，请由对接人员核对实际部署入口和网络可达性

如果要核对谁创建、调整或撤销过Key，或谁修改过身份客户端，可到“审计事件”按事件和对象查询。记录对象、时间、状态与请求标识即可，排查材料不要附完整Secret或Key。