Skip to main content

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​

ScenarioRecommended 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 callbacktcb login --flow web: the callback is received on 127.0.0.1, no user code needed
Remote server / SSH / container / AI agenttcb login: the device code flow needs no local callback
Non-interactive CI/CDtcb login --apiKeyId <SecretId> --apiKey <SecretKey>: account-level Cloud API key
Environment-level long-term credentialtcb login --cloudbase-api-key <key> -e <envId>: permissions limited to one environment
Temporary credentialstcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>
International site accounttcb login --intl true: also persists the site setting
Self-hosted authorization servicetcb login --endpoint <url>: applies to the device code flow only

Command Parameters​

ParameterDescriptionRequired
-k, --keyEnter a Tencent Cloud permanent API key interactivelyNo
--apiKeyId <SecretId>Tencent Cloud API SecretId, used together with --apiKeyNo
--apiKey <SecretKey>Tencent Cloud API SecretKey, used together with --apiKeyIdNo
--token [token]Token of a temporary Tencent Cloud API key, used with the key pairNo
--cloudbase-api-key <key>Environment-level API key, requires -e/--env-idNo
--flow <flow>Authorization flow, device (default) or webNo
--intl [value]Site, only true (international) and false (domestic) are acceptedNo
--endpoint <url>Custom device authorization endpoint, applies to --flow device onlyNo
-e, --env-id <envId>CloudBase environment ID, required when signing in with an environment-level API keyNo

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:

  1. Run tcb login. The CLI prints an authorization link (verification_uri) and a user code (user_code), and tries to open the browser.
  2. Confirm the authorization in the browser. Copy the link manually when the browser does not open.
  3. 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=true applies to --flow web only, 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 true makes 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 false or tcb config set isIntl false
  • You can also run tcb config set isIntl true and then tcb login
  • Precedence: --intl > isIntl in the configuration file > the TCB_IS_INTL environment 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-singapore when a region is required, for example tcb 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.

Temporary credentials only

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]
OptionDescription
-e, --env-id <envId>Bind an environment ID, appended to the output
--jsonOutput 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'
})
warning

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.json in the CLI configuration directory, ~/.config/.cloudbase/ by default (honors XDG_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.json holds 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.