initialization

Initialization

Migration Notice

@cloudbase/node-sdk is no longer maintained (the 4.x next version is entirely based on @cloudbase/js-sdk). Please use @cloudbase/js-sdk v3 directly for development — it already supports all Node.js features.

@Cloudbase/node-sdk lets you use Node.js for server-side access to Cloudbase Service and resources

⚠️ Note: Starting from v3, if the env parameter is not specified in init({}), the current Serverless Cloud Function (SCF) environment ID is used by default, and the cloud development default environment is no longer in use. To use the cloud development default environment, you can specify init({env: tcb.SYMBOL_DEFAULT_ENV}).

Finish MCP setup first, then select a prompt to start your AI-native development journey

Installing the SDK

# npm
npm install @cloudbase/node-sdk -S

# yarn
yarn add @cloudbase/node-sdk

Initialize SDK

Basic Usage

import tcb from "@cloudbase/node-sdk";

// Use commonjs introduction method in SCF environment
// const tcb = require('@cloudbase/node-sdk')

const app = tcb.init({
  env: "your-env-id", // Replace this value with your environment ID
});

Initialize the parameter

Field	Data Type	Required	Description
env	string	No	CloudBase environment ID
accessKey	string	No	Cloudbase API Key, the highest priority authentication method. It can also be configured through the environment variable CLOUDBASE_APIKEY.
secretId	string	No	Tencent Cloud API fixed key pair secretId, go to Tencent Cloud Console/API Key Management to generate. It can also be configured through the environment variable TENCENTCLOUD_SECRETID.
secretKey	string	No	Tencent Cloud API fixed key pair secretKey, go to Tencent Cloud Console/API Key Management to generate. It can also be configured through the environment variable TENCENTCLOUD_SECRETKEY.
sessionToken	string	No	Tencent Cloud API temporary key pair Token, obtained through the role assumption temporary access credential API.
credentials	object	No	Cloudbase private key, containing two strings private_key and private_key_id, used to issue tickets for custom login scenario Log in to Cloud Development Platform/Identity Verification/Log-in Methods and obtain via "private key download" for custom login
context	Context	No	Functional cloud hosting entry function context parameter, used for signature-free calls in cloud hosting scenarios.
timeout	number	No	API call timeout period (ms), defaults to 15000ms, i.e. 15s.
proxy	string	No	http proxy url used when calling API.
version	string	No	Version number, dependency project version number.

Login Authentication

node-sdk uses the following authentication methods in different environments:

During SDK initialization, you can select the authentication method as follows (just choose one of them):

Authentication method	Description
Environment variable TENCENTCLOUD_SECRETID + TENCENTCLOUD_SECRETKEY	No need to input in init, automatically read secretId and secretKey from environment variables, access with role identity of administrator. Only applies to event-triggered Cloud Functions; does NOT apply to Web Cloud Functions (HTTP Cloud Functions)
Use client Publishable Key	Explicitly input Publishable Key in init, access with anonymous role identity
secretId + secretKey (explicit configuration)	Explicitly input secretId and secretKey in init, access with admin role identity
Use server API Key	No need to input in init, automatically read CLOUDBASE_APIKEY from environment variables, configure server API Key to environment variable CLOUDBASE_APIKEY
sessionToken (explicit configuration)	Explicitly input sessionToken in init, access with temporary access credential via role assumption
context.extendedContext	The managed environment automatically obtains temporary key and environment ID from context

Authentication example

Use default authentication

Users do not need to input in init, secretId and secretKey are automatically read from environment variable

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
});

Use Publishable Key

For detailed introduction of Publishable Key, see Documentation Description.

• User permission: anonymous user permission
• Validity Period: long-term valid -Method for obtaining: Obtain from Cloud Development Platform/ApiKey Management.

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  accessKey: "your-publishable-key",
});

Use API Key

You can configure through environment variable CLOUDBASE_APIKEY, enable API key settings in SCF, and add CLOUDBASE_APIKEY.

import tcb from "@cloudbase/node-sdk";

// No need to explicitly input accessKey, the SDK automatically reads from environment variable
const app = tcb.init({
  env: "your-env-id",
});

Use secretId and secretKey

Go to tencent cloud console/API key management to generate secretKey, secretId

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  secretId: "your-secretId",
  secretKey: "your-secretKey",
});

Use sessionToken

Obtain the Token through the submit a request for role assumption Temporary Access Credentials API

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: "your-env-id",
  sessionToken: "your-sessionToken",
});

Examples

SCF Environment

In event-triggered Cloud Function environments, the SDK automatically reads authentication information from the environmental variable without manual configuration of authentication parameters.

import tcb from "@cloudbase/node-sdk";

const app = tcb.init({
  env: tcb.SYMBOL_DEFAULT_ENV, // Use the default environment ID of the current SCF
});

Web Cloud Functions (HTTP Cloud Functions) must explicitly configure authentication

The runtime of a Web Cloud Function (HTTP Cloud Function) does NOT inject the TENCENTCLOUD_SECRETID / TENCENTCLOUD_SECRETKEY auth env vars. Without explicit auth configuration, every API call fails with getCredential failed / secretId or secretKey not found. You must explicitly specify one of the following auth methods:

import tcb from "@cloudbase/node-sdk";

// Option 1 (recommended): set CLOUDBASE_APIKEY in the function env vars, then pass accessKey
const app = tcb.init({
  env: tcb.SYMBOL_DEFAULT_ENV,
  accessKey: process.env.CLOUDBASE_APIKEY,
});

// Option 2: explicitly pass the Tencent Cloud key pair
// const app = tcb.init({
//   env: tcb.SYMBOL_DEFAULT_ENV,
//   secretId: "xxx",
//   secretKey: "xxx",
// });

CloudRun Environment

In a functional managed environment, implement signature-free calls by importing the context parameter.

💡 Note: If the input has the context parameter but no env parameter, then the envID parameter in context will be used as the environment ID.

import tcb from "@cloudbase/node-sdk";

exports.main = async (event, context) => {
  const app = tcb.init({
    context,
  });
};