使用其他凭证方式对接环境

除 API Key 外，云开发还支持通过自定义授权码和临时密钥两种凭证方式，将环境接入您的 Agent 平台。三种方式对比如下：

方式	适用场景	用户感知	配置复杂度
API Key（推荐）	平台统一下发，用户无需任何登录操作	零感知	最低
自定义授权码	用户需要通过自有域名完成一次性授权登录	用户点击自有域名链接	中
临时密钥	平台服务端控制凭证生命周期，定期刷新	零感知	中

自定义授权码

推荐方式。企业自建授权页面代理设备码流程，用户全程在自有域名下完成登录，无需感知腾讯云。

自定义授权页面

企业内部系统需要实现一个自定义授权页面，代理设备码授权流程：

代理设备码申请：当 AI 工具发起登录时，企业系统将设备码申请请求转发至云开发 API
改写授权链接：将云开发返回的授权链接改写为自有域名（如 https://auth.your-domain.com/authorize?code=xxx）
自有认证页面：用户打开改写后的链接，使用企业/平台账号登录
环境选择与授权：登录后展示该用户可用的环境列表，用户选择后完成设备码授权
获取临时密钥：授权完成后，AI 工具通过设备码轮询获取临时密钥

首次登录自动创建环境

当用户首次登录时，企业系统应自动为其创建专属的云开发环境：

调用 CreateEnv 创建环境，详见开通并创建第一个环境
在数据库中记录用户 ID 与环境 ID 的映射关系
后续登录时根据映射直接定位到用户环境

权限策略

授权服务在用户验证通过后，调用 STS GetFederationToken 签发带策略限制的临时凭证，无需创建子账号。

点击查看完整策略模板 JSON

{
  "statement": [
    {
      "action": [
        "cam:CreateRole",
        "cam:AttachRolePolicy",
        "cam:GetRole",
        "cdn:TcbCheckResource",
        "scf:ListFunctions",
        "tcb:CheckTcbService",
        "tcb:DescribeEnvs",
        "tcb:DescribeBillingInfo",
        "tcb:DescribeEnvPostpayPackage",
        "tcb:DeleteTable",
        "tcb:CreateTable",
        "tcb:DescribeTable",
        "tcb:DescribeTables",
        "tcb:ListTables",
        "tcb:RunCommands",
        "tcb:UpdateTable",
        "tcb:UpdateItem",
        "tcb:QueryRecords",
        "tcb:PutItem",
        "tcb:ModifyNameSpace",
        "tcb:DeleteItem",
        "tcb:CountRecords"
      ],
      "effect": "allow",
      "resource": ["*"]
    },
    {
      "action": ["tcb:*"],
      "effect": "allow",
      "resource": ["qcs::tcb::uin/${uin}:env/${envId}"]
    },
    {
      "action": ["tcbr:*"],
      "effect": "allow",
      "resource": ["qcs::tcbr::uin/${uin}:env/${envId}"]
    },
    {
      "action": ["lowcode:*"],
      "effect": "allow",
      "resource": ["qcs::lowcode::uin/${uin}:env/${envId}"]
    },
    {
      "action": ["scf:*"],
      "effect": "allow",
      "resource": [
        "qcs::scf:${region}:uin/${uin}:namespace/${envId}",
        "qcs::scf:${region}:uin/${uin}:namespace/${envId}/function/*",
        "qcs::scf:${region}:uin/${uin}:namespace/${envId}/layer/*",
        "qcs::cls:${region}:uin/${uin}:logset/${logsetId}",
        "qcs::cls:${region}:uin/${uin}:topic/${topicId}"
      ]
    },
    {
      "action": ["cls:*"],
      "effect": "allow",
      "resource": [
        "qcs::cls:${region}:uin/${uin}:logset/${logsetId}",
        "qcs::cls:${region}:uin/${uin}:topic/${topicId}"
      ]
    },
    {
      "action": ["cos:*"],
      "effect": "allow",
      "resource": [
        "qcs::cos:${region}:uid/${appId}:${cosBucketId}/*",
        "qcs::cos:${region}:uid/${appId}:${staticBucketId}/*"
      ]
    }
  ],
  "version": "2.0"
}

占位符说明

占位符	含义	获取方式
`${region}`	环境所在地域	`DescribeEnvs` 返回的 `EnvList[0].Region`
`${uin}`	主账号 UIN	使用主账号密钥调用 `GetUserAppId` 返回的 `Uin`
`${appId}`	主账号 AppId	`DescribeEnvs` 返回的 `EnvList[0].AppId`，或从存储桶名称末段提取
`${envId}`	云开发环境 ID	`DescribeEnvs` 返回的 `EnvList[0].EnvId`
`${topicId}`	CLS 日志主题 ID	`DescribeEnvs` 返回的 `EnvList[0].LogServices[0].TopicId`
`${logsetId}`	CLS 日志集 ID	`DescribeEnvs` 返回的 `EnvList[0].LogServices[0].LogsetId`
`${cosBucketId}`	云存储桶名称	`DescribeEnvs` 返回的 `EnvList[0].Storages[0].Bucket`
`${staticBucketId}`	静态托管存储桶名称	`DescribeEnvs` 返回的 `EnvList[0].StaticStorages[0].Bucket`

tcb 和 tcbr 的资源格式中不含 ${region}，适用于自定义授权码 / 临时密钥场景下的临时凭证。

点击查看 Node.js 签发临时凭证代码示例

// 安装依赖：npm install tencentcloud-sdk-nodejs
// 使用说明：
// 1. 将上方「策略模板」章节的 JSON 内容保存为 policy-template.json
// 2. 设置环境变量：TENCENTCLOUD_SECRETID, TENCENTCLOUD_SECRETKEY
// 3. 在授权服务中调用 issueTemporaryCredentials(envId, userId)

const tencentcloud = require("tencentcloud-sdk-nodejs");
const fs = require("fs");
const path = require("path");

const AccountClient = tencentcloud.account.v20190119.Client;
const TcbClient = tencentcloud.tcb.v20180608.Client;
const StsClient = tencentcloud.sts.v20180813.Client;

const clientConfig = {
  credential: {
    secretId: process.env.TENCENTCLOUD_SECRETID,
    secretKey: process.env.TENCENTCLOUD_SECRETKEY,
  },
  region: "ap-shanghai",
};

const POLICY_TEMPLATE = fs.readFileSync(
  path.join(__dirname, "policy-template.json"),
  "utf8"
);

async function getPolicyVars(envId) {
  const accountClient = new AccountClient(clientConfig);
  const tcbClient = new TcbClient(clientConfig);

  // 授权服务使用主账号密钥调用时，Uin 即策略里的主账号 UIN。
  const [{ Uin }, { EnvList }] = await Promise.all([
    accountClient.GetUserAppId({}),
    tcbClient.DescribeEnvs({ EnvId: envId }),
  ]);
  const env = EnvList[0];
  if (!env) {
    throw new Error(`未查询到云开发环境 ${envId}`);
  }

  return {
    region: env.Region,
    uin: Uin,
    appId: String(env.AppId),
    envId: env.EnvId,
    logsetId: env.LogServices?.[0]?.LogsetId || "",
    topicId: env.LogServices?.[0]?.TopicId || "",
    cosBucketId: env.Storages?.[0]?.Bucket || "",
    staticBucketId: env.StaticStorages?.[0]?.Bucket || "",
  };
}

async function generatePolicy(envId) {
  const vars = await getPolicyVars(envId);
  const policyJson = POLICY_TEMPLATE.replace(
    /\$\{(\w+)\}/g,
    (_, name) => vars[name] || ""
  );
  return JSON.parse(policyJson);
}

async function issueTemporaryCredentials(envId, userId) {
  const stsClient = new StsClient({
    ...clientConfig,
    profile: { httpProfile: { endpoint: "sts.tencentcloudapi.com" } },
  });
  const policy = await generatePolicy(envId);

  const { Credentials } = await stsClient.GetFederationToken({
    Name: `user-${userId}`,
    Policy: JSON.stringify(policy),
    DurationSeconds: 1800, // 30 分钟，可按需调整
  });

  return Credentials; // { TmpSecretId, TmpSecretKey, Token }
}

module.exports = { issueTemporaryCredentials };

API	用途	文档
`GetUserAppId`	获取主账号 UIN 和 AppId	账号相关接口
`DescribeEnvs`	查询云开发环境详情（存储桶、日志主题等）	云开发 API 概览
`GetFederationToken`	STS 签发临时凭证（策略内联传入，无需创建子账号）	STS 接口 GetFederationToken

MCP 配置

TCB_AUTH_OAUTH_ENDPOINT

设置自定义授权 endpoint 后，MCP 的设备码授权流程会跳转到你指定的地址（如 https://auth.your-domain.com），而非腾讯云默认授权页。不设置则使用腾讯云默认授权页。

Client

配置你的 AI 工具以连接 CloudBase 能力支持本地与托管两种连接方式，详见连接方式。

步骤 1：安装 / 配置 CloudBase

使用项目模板（推荐） - 模板已内置 MCP 配置和 AI 规则查看模板

一键安装:

Add to Cursor

或手动配置:

将以下配置添加到项目目录下的 .cursor/mcp.json:

json

1{
2  "mcpServers": {
3    "cloudbase": {
4      "command": "npx",
5      "args": ["@cloudbase/cloudbase-mcp@latest"],
6      "env": {
7        "INTEGRATION_IDE": "Cursor"
8      }
9    }
10  }
11}

需要帮助？查看 Cursor 文档

步骤 2：和 AI 对话

在 AI 对话中依次输入以下内容:

prompt

安装 CloudBase Skills：命令 npx skills add tencentcloudbase/cloudbase-skills -y

使用 CloudBase Skills：使用云开发连接我的环境，授权 endpoint 为 https://auth.your-domain.com

临时密钥

通过腾讯云 STS 的 GetFederationToken 接口签出带策略限制的临时密钥，适合需要服务端控制凭证生命周期的场景。

权限策略

企业系统调用 GetFederationToken，将策略以内联方式传入，签发只能访问指定环境的临时凭证：

点击查看内联策略代码示例

// 将上方签发临时凭证示例保存为 issue-temporary-credentials.js 后复用。
const { issueTemporaryCredentials } = require("./issue-temporary-credentials");

async function getMcpCredentials(envId, userId) {
  // envId 来自你的「用户 ID ↔ 云开发环境 ID」映射关系。
  const credentials = await issueTemporaryCredentials(envId, userId);

  // credentials.TmpSecretId / TmpSecretKey / Token 配置到 MCP。
  return credentials;
}

MCP 配置

Client

配置你的 AI 工具以连接 CloudBase 能力支持本地与托管两种连接方式，详见连接方式。

步骤 1：安装 / 配置 CloudBase

使用项目模板（推荐） - 模板已内置 MCP 配置和 AI 规则查看模板

一键安装:

Add to Cursor

或手动配置:

将以下配置添加到项目目录下的 .cursor/mcp.json:

json

1{
2  "mcpServers": {
3    "cloudbase": {
4      "command": "npx",
5      "args": ["@cloudbase/cloudbase-mcp@latest"],
6      "env": {
7        "INTEGRATION_IDE": "Cursor"
8      }
9    }
10  }
11}

需要帮助？查看 Cursor 文档

步骤 2：和 AI 对话

在 AI 对话中依次输入以下内容:

prompt

安装 CloudBase Skills：命令 npx skills add tencentcloudbase/cloudbase-skills -y

使用 CloudBase Skills：使用云开发操作环境，已通过 MCP 配置临时密钥

密钥过期

临时密钥有有效期（默认 30 分钟，通过 DurationSeconds 配置），过期后需要重新签发。

下一步

对接完成后，即可开始管理环境内的资源：

→ 管理环境的资源

自定义授权码​

自定义授权页面​

首次登录自动创建环境​

权限策略​

占位符说明​

相关 API 参考​

MCP 配置​

步骤 1：安装 / 配置 CloudBase

步骤 2：和 AI 对话

临时密钥​

权限策略​

MCP 配置​

步骤 1：安装 / 配置 CloudBase

步骤 2：和 AI 对话

下一步​

自定义授权码

自定义授权页面

首次登录自动创建环境

权限策略

占位符说明

相关 API 参考

MCP 配置

临时密钥

权限策略

MCP 配置

下一步