Login and Authentication
tcb login signs in to a Tencent Cloud account and authorizes CloudBase CLI to operate your CloudBase resources. Most commands ask you to sign in first when no valid credential is available.
Login Methods
| Scenario | Recommended command |
|---|---|
| Local development (default) | tcb login: device code flow, the terminal prints a link and a user code and also tries to open the browser |
| Local machine with browser callback | tcb login --flow web: the callback is received on 127.0.0.1, no user code needed |
| Remote server / SSH / container / AI agent | tcb login: the device code flow needs no local callback |
| Non-interactive CI/CD | tcb login --apiKeyId <SecretId> --apiKey <SecretKey>: account-level Cloud API key |
| Environment-level long-term credential | tcb login --cloudbase-api-key <key> -e <envId>: permissions limited to one environment |
| Temporary credentials | tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token> |
| International site account | tcb login --intl true: also persists the site setting |
| Self-hosted authorization service | tcb login --endpoint <url>: applies to the device code flow only |
Command Parameters
| Parameter | Description | Required |
|---|---|---|
-k, --key | Enter a Tencent Cloud permanent API key interactively | No |
--apiKeyId <SecretId> | Tencent Cloud API SecretId, used together with --apiKey | No |
--apiKey <SecretKey> | Tencent Cloud API SecretKey, used together with --apiKeyId | No |
--token [token] | Token of a temporary Tencent Cloud API key, used with the key pair | No |
--cloudbase-api-key <key> | Environment-level API key, requires -e/--env-id | No |
--flow <flow> | Authorization flow, device (default) or web | No |
--intl [value] | Site, only true (international) and false (domestic) are accepted | No |
--endpoint <url> | Custom device authorization endpoint, applies to --flow device only | No |
-e, --env-id <envId> | CloudBase environment ID, required when signing in with an environment-level API key | No |
With no parameters the CLI uses the device code flow.
Local Login
tcb login
The CLI uses the device code flow by default (OAuth 2.0 Device Authorization Grant, RFC 8628). The terminal that starts the login does not have to be the machine where authorization is confirmed:
- Run
tcb login. The CLI prints an authorization link (verification_uri) and a user code (user_code), and tries to open the browser. - Confirm the authorization in the browser. Copy the link manually when the browser does not open.
- The CLI polls the authorization state and saves the credential once it succeeds.
When a valid credential already exists, tcb login returns a success message and skips the authorization flow. Run tcb logout first to change the method or the account.
Browser Callback Flow
On a machine with a graphical interface, the CLI can open the browser and finish authorization through a local callback, without entering a user code:
tcb login --flow web
In this flow the CLI starts a temporary HTTP service on a random local port and receives the result on http://127.0.0.1:<port>. The machine must therefore both open the browser and accept the callback (the default callback timeout is 10 minutes). Use the default device code flow on remote servers, containers, and headless environments.
TCB_NO_BROWSER=trueapplies to--flow webonly, where it stops the browser from opening automatically. The device code flow ignores it.
Remote and Headless Environments
Remote servers, SSH sessions, Docker / Kubernetes containers, CI runners, and AI coding assistants (Claude Code, Codex and others that call the CLI through MCP tools) all use the default device code flow:
tcb login
Copy the authorization link and user code printed in the terminal, open them on any device with a browser, and confirm. The CLI polls the result, so no port mapping and no local callback are needed.
Without a browser, the failed attempt to open one is ignored and the link and user code are still printed.
Cloud API Key Login
If you already have a Tencent Cloud Cloud API key, you can skip browser authorization.
Interactive Input
tcb login -k
Enter SecretId and SecretKey when prompted. Create or view keys on the Cloud API key management page.
⚠️ A Tencent Cloud API key can operate every Tencent Cloud resource under your account. Store it safely, rotate it regularly, and delete the old key after rotating.
Non-interactive Login
Scripts and pipelines pass the key as parameters:
# Permanent key
tcb login --apiKeyId <SecretId> --apiKey <SecretKey>
# Temporary key
tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>
⚠️ An account-level key can operate every Tencent Cloud resource under your account. Keep it in CI secrets and never commit it to a repository.
Environment-level API Key
An environment-level API key is a long-term CloudBase credential scoped to a single environment, which suits per-environment isolation:
tcb login --cloudbase-api-key <key> -e <envId>
-e/--env-id is required. See Create an API key for how to create one.
GitHub Actions Example
- name: Login to CloudBase
run: npx @cloudbase/cli login --cloudbase-api-key ${{ secrets.CLOUDBASE_API_KEY }} -e ${{ secrets.CLOUDBASE_ENV_ID }}
International Site Login
Specify the site explicitly when signing in to an international site account:
tcb login --intl true
--intl truemakes the current login use the international site immediately, switching both the authorization page and the OAuth endpoint, and persists the setting- Switch back with
tcb login --intl falseortcb config set isIntl false - You can also run
tcb config set isIntl trueand thentcb login - Precedence:
--intl>isIntlin the configuration file > theTCB_IS_INTLenvironment variable > domestic site by default - Site and region are independent, switching the site does not change the region. International environments are usually in Singapore, add
-r ap-singaporewhen a region is required, for exampletcb env list -r ap-singapore
Custom Authorization Endpoint
Enterprises can point device authorization at a self-hosted service:
tcb login --endpoint https://your-auth-server.example.com
The CLI calls /device/code and then /token on the given endpoint to obtain credentials. The option applies only to --flow device (the default). The service must follow the CloudBase CLI Device Flow protocol, see Device code authorization overview and Self-hosted device code authorization service.
Verify the Login
tcb env list
Listing environments means the login succeeded. If the CLI reports that you are not signed in, that the credential expired, or the list is empty, run tcb login again. International site accounts should also check the region parameter (see International Site Login).
Get Temporary Credentials
tcb secrets get reads the temporary credentials (secretId / secretKey / token) of the current web login session, so you can initialize @cloudbase/manager-node or @cloudbase/node-sdk locally for debugging without configuring anything by hand.
Permanent keys passed to tcb login --key cannot be output. A leaked permanent key is compromised forever, so do not use this command for them.
tcb secrets get [options]
| Option | Description |
|---|---|
-e, --env-id <envId> | Bind an environment ID, appended to the output |
--json | Output JSON |
tcb secrets get --json -e my-env-id
{
"secretId": "AKID...",
"secretKey": "xxx",
"token": "yyy",
"expiredAt": "2026-03-30 22:00:00",
"isTemporary": true,
"envId": "my-env-id"
}
Initialize the SDK with the output:
// @cloudbase/manager-node
const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({
secretId: '<secretId>',
secretKey: '<secretKey>',
token: '<token>',
envId: 'my-env-id'
})
// @cloudbase/node-sdk
const tcb = require('@cloudbase/node-sdk')
const tcbApp = tcb.init({
secretId: '<secretId>',
secretKey: '<secretKey>',
token: '<token>',
env: 'my-env-id'
})
Temporary credentials expire automatically. Do not commit them or paste them in public channels.
Sign Out and Switch Accounts
tcb logout
tcb logout clears the local credential, including project-level credentials, and the current environment record. To switch accounts, sign out and run tcb login again.
Credential Storage and Security
- Credentials are stored in
auth.jsonin the CLI configuration directory,~/.config/.cloudbase/by default (honorsXDG_CONFIG_HOME) - When signing in with an environment-level API key, the credential may be written to project-level storage that matches the project directory at login time
auth.jsonholds identity credentials. Do not commit it or share it- Prefer injecting long-term keys through CI secrets or environment variables instead of hardcoding them in scripts and configuration files
FAQ
Empty environment list
- The account has no environment yet, create one in the console
- An international site account without a region, try
tcb env list -r ap-singapore - The sub-account lacks permissions, see Sub-account authorization
Browser cannot open the authorization page
Use the default device code flow and copy the link and user code printed in the terminal. TCB_NO_BROWSER=true has no effect on the device code flow, it only affects --flow web.
Local callback fails
--flow web requires access to a random port on 127.0.0.1. On remote servers, in containers, or behind port restrictions, use the default --flow device.
Permission denied
Check the account and environment ownership. An environment-level API key can only operate the environment it was created for, while an account-level key is limited by CAM policies.