Connect Environments with Other Credentials

In addition to API Key, CloudBase also supports connecting environments to your Agent platform through custom auth code and temporary keys. A comparison of the three methods:

Method	Applicable scenario	User awareness	Configuration complexity
API Key (recommended)	The platform delivers it uniformly; users do not need any login operations	Zero awareness	Lowest
Custom auth code	Users need to complete a one-time authorization login through their own domain	Users click an own-domain link	Medium
Temporary keys	The platform server side controls the credential lifecycle and refreshes regularly	Zero awareness	Medium

Custom Auth Code

Recommended method. Enterprises build their own authorization page to proxy the device code flow; users complete login entirely under their own domain without being aware of Tencent Cloud.

Custom Authorization Page

The enterprise internal system needs to implement a custom authorization page that proxies the device code authorization flow:

Proxy device code application: when the AI tool initiates login, the enterprise system forwards the device code application request to the CloudBase API
Rewrite the authorization link: rewrite the authorization link returned by CloudBase to an own domain (e.g., https://auth.your-domain.com/authorize?code=xxx)
Own authentication page: users open the rewritten link and log in with their enterprise/platform account
Environment selection and authorization: after login, show the list of environments available to the user; the user selects one to complete device code authorization
Get temporary keys: after authorization, the AI tool polls for temporary keys through the device code

Auto-Create an Environment on First Login

When a user logs in for the first time, the enterprise system should automatically create an exclusive CloudBase environment for them:

Call CreateEnv to create an environment, see Enable and create your first environment
Record the mapping between the user ID and environment ID in the database
On subsequent logins, locate the user's environment directly based on the mapping

Permission Policy

After user verification passes, the authorization service calls STS GetFederationToken to issue policy-restricted temporary credentials, without creating sub-accounts.

Click to view the full policy template 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"
}

Placeholder Description

Placeholder	Meaning	How to get it
`${region}`	Region of the environment	`EnvList[0].Region` returned by `DescribeEnvs`
`${uin}`	UIN of the main account	`Uin` returned by calling `GetUserAppId` with the main account key
`${appId}`	AppId of the main account	`EnvList[0].AppId` returned by `DescribeEnvs`, or extracted from the end of the bucket name
`${envId}`	CloudBase environment ID	`EnvList[0].EnvId` returned by `DescribeEnvs`
`${topicId}`	CLS log topic ID	`EnvList[0].LogServices[0].TopicId` returned by `DescribeEnvs`
`${logsetId}`	CLS logset ID	`EnvList[0].LogServices[0].LogsetId` returned by `DescribeEnvs`
`${cosBucketId}`	Cloud storage bucket name	`EnvList[0].Storages[0].Bucket` returned by `DescribeEnvs`
`${staticBucketId}`	Static hosting bucket name	`EnvList[0].StaticStorages[0].Bucket` returned by `DescribeEnvs`

The resource formats of tcb and tcbr do not contain ${region}, which is suitable for temporary credentials in the custom auth code / temporary key scenarios.

Click to view the Node.js sample for issuing temporary credentials

// Install dependency: npm install tencentcloud-sdk-nodejs
// Usage:
// 1. Save the JSON content from the "Policy Template" section above as policy-template.json
// 2. Set environment variables: TENCENTCLOUD_SECRETID, TENCENTCLOUD_SECRETKEY
// 3. Call issueTemporaryCredentials(envId, userId) in the authorization service

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);

  // When the authorization service calls with the main account key, Uin is the main account UIN in the policy.
  const [{ Uin }, { EnvList }] = await Promise.all([
    accountClient.GetUserAppId({}),
    tcbClient.DescribeEnvs({ EnvId: envId }),
  ]);
  const env = EnvList[0];
  if (!env) {
    throw new Error(`CloudBase environment not found: ${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 minutes, adjust as needed
  });

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

module.exports = { issueTemporaryCredentials };

Related API Reference

API	Purpose	Documentation
`GetUserAppId`	Get the UIN and AppId of the main account	Account-related APIs
`DescribeEnvs`	Query CloudBase environment details (buckets, log topics, etc.)	CloudBase API overview
`GetFederationToken`	STS issues temporary credentials (policy passed inline, no sub-account creation needed)	STS API GetFederationToken

For the complete reference implementation, see cloudbase-cli-auth-endpoint; for the integration guide, see Enterprise self-built device code authorization service integration.

MCP Configuration

TCB_AUTH_OAUTH_ENDPOINT

After setting a custom authorization endpoint, the MCP device code authorization flow jumps to the address you specify (e.g., https://auth.your-domain.com) instead of the Tencent Cloud default authorization page. If not set, the Tencent Cloud default authorization page is used.

Client

Configure your AI tool to connect with CloudBase capabilities. Supports local and hosted connection. See connection modes.

Step 1: Install / Configure CloudBase

Use project template (recommended) - Template includes MCP configuration and AI rulesView templates

Install in one click:

Add to Cursor

Or manual configuration:

Or add this configuration to .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}

Need help?View Cursor docs

Step 2: Chat with AI

Enter the following in your AI chat in order:

prompt

Install CloudBase Skills: run npx skills add tencentcloudbase/cloudbase-skills -y

Use CloudBase Skills: Use CloudBase to connect to my environment; the authorization endpoint is https://auth.your-domain.com

Temporary Keys

Issue policy-restricted temporary keys through the GetFederationToken API of Tencent Cloud STS, suitable for scenarios where the server side needs to control the credential lifecycle.

Permission Policy

The enterprise system calls GetFederationToken, passes the policy inline, and issues temporary credentials that can only access the specified environment:

Click to view the inline policy code sample

// Save the above sample for issuing temporary credentials as issue-temporary-credentials.js and reuse it.
const { issueTemporaryCredentials } = require("./issue-temporary-credentials");

async function getMcpCredentials(envId, userId) {
  // envId comes from your "user ID ↔ CloudBase environment ID" mapping.
  const credentials = await issueTemporaryCredentials(envId, userId);

  // Configure credentials.TmpSecretId / TmpSecretKey / Token into the MCP.
  return credentials;
}

MCP Configuration

Client

Configure your AI tool to connect with CloudBase capabilities. Supports local and hosted connection. See connection modes.

Step 1: Install / Configure CloudBase

Use project template (recommended) - Template includes MCP configuration and AI rulesView templates

Install in one click:

Add to Cursor

Or manual configuration:

Or add this configuration to .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}

Need help?View Cursor docs

Step 2: Chat with AI

Enter the following in your AI chat in order:

prompt

Install CloudBase Skills: run npx skills add tencentcloudbase/cloudbase-skills -y

Use CloudBase Skills: Use CloudBase to operate the environment; temporary keys have been configured through the MCP

Key expiration

Temporary keys have a validity period (default 30 minutes, configured through DurationSeconds), and need to be re-issued after expiration.

Next Steps

After the integration is complete, you can start managing resources within the environment:

→ Manage environment resources

Custom Auth Code​

Custom Authorization Page​

Auto-Create an Environment on First Login​

Permission Policy​

Placeholder Description​

Related API Reference​

MCP Configuration​

Step 1: Install / Configure CloudBase

Step 2: Chat with AI

Temporary Keys​

Permission Policy​

MCP Configuration​

Step 1: Install / Configure CloudBase

Step 2: Chat with AI

Next Steps​

Custom Auth Code

Custom Authorization Page

Auto-Create an Environment on First Login

Permission Policy

Placeholder Description

Related API Reference

MCP Configuration

Temporary Keys

Permission Policy

MCP Configuration

Next Steps