文档中心

AgentKit

管理凭据

轮换密钥

轮换密钥用于更新 AgentKit 托管的 API Key 或 OAuth 客户端密钥（Client Secret）。当原密钥即将过期、疑似泄露，或需要按照安全策略定期更新时，可以执行密钥轮换。轮换后，AgentKit 将立即使用新值替换旧值，旧值不会保留，也无法恢复。凭据原有的 Agent 绑定关系不受影响，后续出站调用将使用新的客户端密钥。

推荐场景

定期更新密钥

建议定期轮换客户端密钥，缩短长期密钥的持续使用周期。

处理疑似泄露风险

当原客户端密钥可能被泄露、误提交至代码仓库，或出现在日志和配置文件中时，应尽快生成新密钥并完成轮换。

同步第三方平台的密钥变更

在第三方服务提供方生成新的客户端密钥后，需要同步更新 AgentKit 中托管的密钥，确保 Agent 能够继续正常访问目标服务。

调整密钥权限或有效期

当原密钥的权限范围、适用环境或有效期不再满足业务要求时，可创建符合新要求的客户端密钥，并通过轮换操作完成替换。

使用限制

不同凭据类型对于密钥轮换能力的支持存在差异：

凭据类型	是否支持更换密钥	说明
API Key	支持	密钥轮换完成后，新客户端密钥将立即覆盖替换旧值；该凭据已有的 Agent 绑定关系保持不变，不会受密钥轮换操作影响。
OAuth 连接	部分支持	提供商类型为飞书、Coze、Github、自定义的 OAuth 连接支持轮换密钥。轮换生效后，后续发起的 OAuth 授权流程、令牌获取请求将统一使用新的客户端密钥。说明提供商类型为用户池的 OAuth 连接，不支持轮换密钥，其客户端密钥由用户池客户端托管，应前往对应的用户池客户端处理，详情请参见编辑客户端。
火山云角色	不支持	火山云角色凭据不依赖 API Key 或 OAuth 客户端密钥，不存在密钥载体，因此不支持密钥轮换功能。

前提条件

获取有效的新密钥

根据凭据类型，在对应的第三方平台生成新值：

API Key：已从目标服务提供方获取可用的 API Key，并确认该密钥具备 Agent 调用目标服务所需的权限。建议同时确认密钥的适用环境、有效期、调用额度、访问范围及是否存在 IP 白名单等限制，避免创建完成后因密钥权限不足或环境不匹配导致调用失败。

OAuth 连接：在身份提供商的开发者平台或 OAuth 应用管理页面，为当前 OAuth 应用生成新的 Client Secret。不同提供商的创建方式和凭据名称可能不同，请参考下表：

提供商类型	准备工作	参考文档
GitHub	创建 OAuth App，配置 Homepage URL 和 Authorization callback URL，并获取Client Secret。	创建 OAuth App
飞书	创建或打开飞书应用，在“基础信息 > 凭证与基础信息”中获取 App Secret，App Secret 对应客户端密钥。	如何获取应用的 App ID 和 App Secret
Coze	创建 OAuth 应用，并获取 Client Secret。创建 OAuth 应用时，回调地址填写 AgentKit 当前 OAuth 流程实际使用的地址。	创建 OAuth 应用并获取客户端凭据
自定义	前往目标身份提供商的开发者平台创建 OAuth 客户端，并根据其官方文档配置回调地址、权限范围及其他 OAuth 参数。	以目标身份提供商的官方文档为准。

确认权限、额度和适用环境

确认客户端密钥具备 Agent 调用目标服务所需的接口权限和调用额度，并与当前业务环境一致，例如测试环境或生产环境，避免因权限不足、额度受限或环境不匹配导致调用失败。

检查访问限制

确认目标服务是否配置 IP 白名单、地域限制、来源域名或其他认证限制。存在来源 IP 限制时，请先确认 AgentKit 实际发起出站请求所使用的出口 IP，并将其添加到目标服务的允许范围。网络配置说明请参见创建运行时。

更换完成后，建议通过目标 Agent 发起一次低风险测试调用，确认网络连接正常且请求未被白名单、地域或其他安全策略拦截。

操作步骤

在左侧导航树，选择“身份与权限 > 凭据管理”。

在目标凭据“操作”列，单击“轮换密钥”按钮。

确认待轮换的凭据名称无误，在“新的 API Key” 输入框粘贴从第三方服务提供方获取的新密钥。

确认新密钥无误后，单击“确认轮换”按钮，完成操作。

后续步骤

AgentKit 内的凭据轮换操作仅替换平台侧托管存储的密钥值，不会自动在第三方服务平台撤销旧密钥。验证新密钥调用正常、完成平台托管值更新后，您可以按需进行如下操作：

API Key 类型凭据

平台不会自动停用或删除第三方服务中的原 API Key。请前往第三方服务控制台停用或删除密钥，并验证旧密钥已无法使用。

OAuth 连接类型凭据

平台不会保证身份提供商已签发的访问令牌、刷新令牌或用户授权同步失效。如需立即终止访问，请在身份提供商侧撤销令牌、取消授权，必要时停用或删除对应的 OAuth 客户端。

最近更新时间：2026.10.23 16:53:59

这个页面对您有帮助吗？

有用

无用