扣子主子账号的 API 密钥权限怎么分配,客服智能体上生产时角色与作用域怎么拆?
主账号只保留成员管理、密钥审批与账单,不签发业务调用令牌;子账号按一人一令牌、一环境一令牌、一渠道一令牌领取最小作用域的密钥,并由服务端统一托管、定期轮换。只有一个使用者的单人试用场景可以简化处理。
扣子(Coze)主子账号的 API 密钥分配原则是:主账号只保留成员管理、密钥审批与账单查看,不签发用于业务调用的令牌;子账号按一人一令牌、一环境一令牌、一渠道一令牌的方式,领取勾选了最小作用域的密钥,并统一放在服务端托管。这个原则适用于已开通团队空间、智能体对外接待的场景;个人空间只有一个使用者、没有对外流量时,共用一个令牌的风险低于维护成本,可以简化。
扣子的密钥权限实际由成员角色和令牌作用域共同决定,最终生效的是两者中更严格的一方,并不是单独一层开关。成员在空间里的角色,决定他能看到哪些智能体、工作流和知识库;令牌勾选的作用域,决定这个密钥能调用哪些接口。所以给子账号开权限时要先定角色、再定令牌作用域,只改其中一层通常是白忙:人能进后台但接口调不通,或者令牌被随手放宽到业务用不到的范围。
扣子里常见的两类调用凭证要分开看。个人访问令牌由成员自己创建,代表个人身份发起调用;OAuth 授权应用用于第三方系统在自己应用里代用户授权访问,凭证不落到最终使用者手上。前者适合内部脚本和自建客服后台,后者适合对外分发或多租户的接待场景;混用会把人的权限和系统的权限绑死,人一离职或转岗,线上客服链路跟着断。
角色分层的第一件事,是把能改和能调分开。空间所有者只负责成员进出、密钥审批和账单,日常不持有调用令牌;智能体维护者负责编排、知识库写入和渠道发布;客服运营与外部系统只拿调用类令牌,不能有知识库写入、成员管理和渠道配置权限。这样任何一次误删知识库或误改发布配置,都能顺着角色定位到具体的人。
令牌作用域要按调用链倒推,而不是照着控制台菜单逐项勾选。一个客服智能体上线后典型链路是:接待窗口发起会话、读取回复、查询历史会话、必要时触发工作流;它不需要创建或删除智能体、不需要管理知识库、不需要改发布渠道。把作用域收敛到会话与工作流执行这一层,密钥泄露后的损失上限是一段时间的对话调用,而不是整个空间的资产。
环境隔离比人员隔离更容易被忽略,因为同一批人往往同时在改和用。给开发、预发、生产各建一套令牌,开发令牌只绑测试智能体和测试知识库,生产令牌只绑线上智能体;否则联调时的批量写入会污染线上知识库,而这类事故在调用日志里通常只表现为某个密钥突然多调了几千次,很难反推到具体操作。
一个渠道配一个密钥,是缩小泄露影响范围最省事的做法。网页客服、公众号、飞书或钉钉、自建后台、第三方外包各发一个令牌,任何一个渠道要下线或疑似泄露,只吊销对应的那一个,其他渠道不停服。混用一个令牌时,排查只能靠时间点和来源 IP,最后往往只能全量重置,等于一次小事故换来一次全渠道停摆。
令牌必须有有效期,并且用新旧并行轮换,避免到期直接切换。创建令牌时可以先设一个较短的期限(可选范围以当前控制台为准),运维在到期前一周创建新令牌,新旧并行一段时间、观察调用量和错误率是否正常,再吊销旧令牌。直接切换最容易在非工作时间触发客服不可用,而客服不可用直接对应询单流失。
密钥放在哪里,决定前面这套分配是否白做。令牌只能存在服务端,由后端或网关代为调用,禁止写进网页、小程序、APP 前端,禁止硬编码进代码仓库,也不要拼在 URL 参数里被访问日志和浏览器历史带走。前端直连的写法一旦上线,作用域收得再小,也等于把密钥对所有人公开。
权限分配要配一份可核对的密钥清单,否则半年后没人说得清哪个密钥还活着。清单至少记四项:密钥负责人、绑定的智能体与渠道、创建时间与到期时间、上一次轮换时间。人一离职、外包一结束、活动一收尾,就按清单吊销;没有清单的团队,往往要等到一次安全扫描才想起清理历史密钥。
计费和配额也要按密钥维度切开。令牌本身不产生费用,产生费用的是背后的模型调用与会话消耗(具体额度与计费方式以官方说明为准);把不同业务线、不同渠道的调用分开,才能在某一渠道异常放量时单独限流,而不是整个空间一起被拖慢或超额。
三种常见分法都是错的:主账号令牌全团队共用一个、给运营开空间管理员顺带拿到密钥管理权、拿生产令牌跑日常调试。前两种让泄露即全损且无法审计,第三种会把测试数据写进线上知识库。判断标准很直接:每个令牌都要能回答谁在用、为什么用、泄露了影响哪个渠道这三个问题,回答不上来就是没分对。
落地可以先做最小版本:主账号留一个只用于创建和吊销令牌的凭证,客服前台一个只含会话与工作流执行作用域的生产令牌,开发环境单独一套,全部托管在服务端,配上到期提醒和清单。等接入第二个渠道或第二个外部团队,再按渠道和调用方拆细;反过来说,如果只有一个渠道、一个使用者、一次内部试用,这套分层可以晚一点上。