API Key 管理

创建好环境后（按需创建或预创建分配），您需要为每一位用户（员工、客户、租户）的环境签发访问凭证——API Key。

平台版环境下，云开发提供 API Key 作为环境访问凭证：API Key 由云开发平台绑定到指定的环境 ID，在服务端强制校验，权限始终限定在本环境范围内，即使泄露也只能访问该用户自己的环境，无法横向访问其他用户的环境数据。API Key 是平台版场景下唯一推荐的环境访问方式。

接入总览

整个平台版接入分为三步：

购买并创建环境：购买平台版套餐，详见购买与初始化；创建环境（按需创建或预创建），详见创建环境
API Key 管理：为每个环境签发 API Key 并下发给用户（本文）
使用 API Key 对接环境：用户将 API Key 配置到 Agent 工具中，即可操作自己的环境，详见使用 API Key 对接环境

整体流程如下：

API Key 权限模型

平台版环境下，API Key 遵循 最小权限 + 按环境隔离 原则，权限由两层约束共同决定，由粗到细逐层收敛：

层级	配置方	作用范围	约束内容
系统安全基线	平台内置，不可修改、不可绕过	整个平台	不能删除环境、不能查看 / 生成 / 吊销 API Key、只能操作本环境自身资源
环境级权限	创建 API Key 时配置	单个环境	白名单 / 黑名单两种模式，按「功能 × 读/写」粒度授权

即使密钥泄露，也只能操作该环境自身已授权的资源：无法删除环境、无法读写其他 API Key、无法访问其他环境的数据。

平台方使用账号的 SecretId / SecretKey 调用云 API 创建环境后，直接为每个环境生成 API Key，并在生成时按需设置该环境的权限即可。权限配置不涉及套餐级别，全部绑定在具体环境的 API Key 上。

权限配置模式

创建 API Key 时，可选择以下两种配置模式：

模式	行为	适用场景
白名单	只授予勾选的功能 × 读/写权限，未勾选的功能无权限	最小权限：API Key 只需访问少数功能时，最安全、最清晰
黑名单	默认授予全部功能 × 读/写权限，仅拒绝勾选的功能	便捷配置：API Key 需要大部分功能、仅排除少数高风险项时

权限按「功能 × 读/写」表达（例如「云数据库-可读」「身份源-可写」），您无需理解底层接口，功能与接口的映射由平台维护
无论哪种模式，最终权限都不越过系统安全基线
可配置的功能范围（如云数据库、身份源、云函数等）以云开发控制台实际展示为准
修改权限后默认约 2 小时内生效；修改时同步清空该 API Key 的临时密钥缓存，可即时生效

创建 API Key

调用腾讯云 CreateApiKey 接口，为用户环境创建 api_key 类型密钥。创建时可选填权限配置（白名单 / 黑名单模式及功能 × 读/写授权），不填则按默认权限授予，具体参数见接口文档：

// 示例：为用户环境创建 API Key
const result = await tcbClient.CreateApiKey({
  EnvId: userEnvId, // 用户的云开发环境 ID
  KeyType: "api_key", // 服务端管理员级密钥
  KeyName: `user-${userId}`,
  // ExpireIn: 7776000    // 可选：有效期（秒），不填则不过期
});
// result.ApiKey 为密钥明文，仅返回一次，请妥善保存

控制台手动创建

也可在控制台手动创建：云开发控制台 → 环境 → API Key 管理。

下发给用户

平台通过自有渠道（站内信、邮件等）将 CLOUDBASE_ENV_ID 与 CLOUDBASE_API_KEY 分配给对应的用户。用户在 Agent 工具的 MCP 配置中填入环境 ID + API Key，即可直接操作自己的云开发环境，无需任何额外登录流程。

安全注意事项

安全提示

api_key 拥有本环境已授权功能对应的读写权限。可通过安全渠道供用户配置本地 MCP，或仅保存在平台服务端；不得写入业务前端、浏览器可执行代码、应用代码仓库或公开渠道。建议定期轮换，单环境最多创建 5 个。

下一步

完成 API Key 管理后，即可将环境接入您的 Agent 平台：

→ 使用 API Key 对接环境

接入总览​

API Key 权限模型​

权限配置模式​

创建 API Key​

控制台手动创建​

下发给用户​

安全注意事项​

下一步​