tencent cloud

Tencent WorkBuddy Enterprise

DocumentationTencent WorkBuddy EnterpriseCodeBuddyCodeBuddy CodeSecurityIdentity and Access Management

Identity and Access Management

Download
Focus Mode
Font Size
Last updated: 2026-10-08 11:03:22
AI-Translated

Overview

Configure user authentication, authorization, and access control for CodeBuddy Code in your organization.

Authentication method

Getting Started

Select an authentication method based on your scenario:
Scenario
Recommended Method
How to Obtain Credentials
Individual developer
CODEBUDDY_API_KEY
Enterprise/team (OAuth integration)
apiKeyHelper
Existing OAuth token in CI/CD.
CODEBUDDY_AUTH_TOKEN
Use the existing token directly.
Third-party model service
CODEBUDDY_API_KEY + BASE_URL
Obtain from the third-party service provider.
Note:
When multiple authentication methods are configured simultaneously, they take effect in the following priority order: CODEBUDDY_AUTH_TOKEN > apiKeyHelper > CODEBUDDY_API_KEY

For Individual Users: Obtaining an API Key

It is suitable for individual developers to get started quickly by using the model services provided by the CodeBuddy platform.
Step 1: Obtain an API Key.
Visit the corresponding platform to obtain your API Key:
Version
Obtaining the Address
Overseas Edition
China Edition
Step 2: Configure environment variables.
Note:
You must correctly configure the CODEBUDDY_INTERNET_ENVIRONMENT environment variable!
This is the configuration item most commonly missed by users. If it is not set or is set incorrectly, authentication will fail or the connection will be made to the wrong service endpoint.
Configure the corresponding environment variables based on the version you are using:
Overseas edition:
export CODEBUDDY_API_KEY="your-api-key"
# No need to set CODEBUDDY_INTERNET_ENVIRONMENT for the overseas edition (default value)
China edition:
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=internal
Dedicated edition:
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=cloudhosted
Self-hosted deployment:
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=selfhosted
Version
CODEBUDDY_INTERNET_ENVIRONMENT Value
Description
Overseas Edition
Not set
Default value. Connects to overseas services.
China Edition
internal
Connects to services in the China region.
Dedicated Edition
cloudhosted
Connects to enterprise instances managed by Tencent Ops.
Private Deployment
selfhosted
Connects to customer self-built enterprise services.
For the dedicated edition or self-hosted deployment, you must also specify the service address: The service address for these two editions is customized by the enterprise (for example, https://your-company.copilot.qq.com). Setting only the environment variable is not sufficient to direct requests to the enterprise service. When using the CLI, enter the address in "Enterprise Domain Configuration" during the login process, and it will be automatically written to settings.json. When using an API Key, configure it manually. For details, see CODEBUDDY_API_KEY. When using the SDK, pass it through options.endpoint.
Persistence configuration recommendation: Add the environment variables to ~/.bashrc, ~/.zshrc, or your shell configuration file to avoid setting them manually each time.
# Add to ~/.zshrc or ~/.bashrc
echo 'export CODEBUDDY_API_KEY="your-api-key"' >> ~/.zshrc
echo 'export CODEBUDDY_INTERNET_ENVIRONMENT=internal' >> ~/.zshrc  # China edition
source ~/.zshrc
Step 3: Get started.
codebuddy

For Enterprise Users: OAuth Authentication

Suitable for enterprise/team integration, where a token is obtained through OAuth 2.0.
Note:
Currently, only the Client Credentials authorization method is introduced, which is suitable for server-side applications and CI/CD scenarios.
Prerequisites: Enterprise users must purchase CodeBuddy Enterprise Ultimate before they can use OAuth authentication. For details, see Team Edition Quick Start.
Step 1: Create an application and obtain the Client ID and Secret.
Complete the steps by referring to Enterprise Developer Quick Start:
1. Create an enterprise application
2. Obtain the Client ID and Client Secret
Step 2: Create a script to obtain a token.
#!/bin/bash
# get-oauth-token.sh - OAuth 2.0 Client Credentials flow

CLIENT_ID="${OAUTH_CLIENT_ID}"
CLIENT_SECRET="${OAUTH_CLIENT_SECRET}"
TOKEN_URL="https://copilot.tencent.com/oauth2/token"

response=$(curl -s -X POST "$TOKEN_URL" \\
  -H "Content-Type: application/x-www-form-urlencoded" \\
  -d "grant_type=client_credentials" \\
  -d "client_id=$CLIENT_ID" \\
  -d "client_secret=$CLIENT_SECRET")

echo "$response" | jq -r '.access_token'
Step 3: Configure apiKeyHelper.
Configure in ~/.codebuddy/settings.json or the project .codebuddy/settings.json:
{
  "apiKeyHelper": "/path/to/get-oauth-token.sh"
}
After the configuration is complete, you can use the codebuddy command.
Note:
Tokens obtained by apiKeyHelper are cached for 5 minutes by default. You can adjust this duration by using the CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS environment variable (in milliseconds).

Third-Party Model Services

It is suitable for using third-party model services such as OpenRouter.
Note:
When using third-party model services, you do not need to set the CODEBUDDY_INTERNET_ENVIRONMENT environment variable because requests are sent directly to the third-party service endpoint.
export CODEBUDDY_API_KEY="sk-or-v1-xxx"
export CODEBUDDY_BASE_URL="https://openrouter.ai/api/v1"
codebuddy --model openai/gpt-4

Authentication Methods Explained

CODEBUDDY_API_KEY

Static API keys are suitable for most scenarios.
Feature
Description
Environment Variable
CODEBUDDY_API_KEY
Authentication Type
API Key (X-Api-Key request header)
Scenario
Personal development, third-party model services
Note:
When using an API Key, you must also configure the CODEBUDDY_INTERNET_ENVIRONMENT environment variable.
Version
Value
Overseas Edition
Not set (default)
China Edition
internal
iOA Edition
ioa
Dedicated Edition
cloudhosted
Private Deployment
selfhosted
# Overseas Edition
export CODEBUDDY_API_KEY="your-api-key"

# China Edition
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

# iOA Edition
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=ioa

# Dedicated Edition (The service address is customized by the enterprise and must also be configured in settings.json. See the instructions below.)
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=cloudhosted

# Private Deployment (The service address is customized by the enterprise and must also be configured in settings.json. See the instructions below.)
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=selfhosted

Dedicated / Private Deployment: Also Configure the Enterprise Service URL in settings.json

For these two editions, the service address is customized by the enterprise. Setting only the CODEBUDDY_INTERNET_ENVIRONMENT variable is not sufficient to direct requests to the enterprise service. You must also add the configuration in ~/.codebuddy/settings.json:
{
  "endpoint": "https://your-company.copilot.qq.com"
}
If this address is not configured, requests are sent to the default public network service address, which typically results in authentication failures or an inability to retrieve the enterprise model list. When login is performed through the CLI, this address is automatically written by the "Enterprise Domain Configuration" step in the login process, so manual editing is not required.

CODEBUDDY_AUTH_TOKEN

An obtained OAuth Bearer Token, suitable for CI/CD or scenarios where a token already exists.
Feature
Description
Environment Variable
CODEBUDDY_AUTH_TOKEN
Authentication Type
Bearer Token (Authorization request header)
Scenario
CI/CD automation and existing OAuth token
export CODEBUDDY_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."
You can also configure it in settings.json:
{
  "env": {
    "CODEBUDDY_AUTH_TOKEN": "your-oauth-token"
  }
}

apiKeyHelper

Dynamically obtain a token through a script, suitable for OAuth integration or scenarios where the token needs to be refreshed periodically.
Feature
Description
Configuration Method
The apiKeyHelper field in settings.json
Authentication Type
Bearer Token (returned by the script)
Caching Mechanism
Defaults to 5 minutes and can be configured through CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS.
Scenario
OAuth Client Credentials, Vault integration, and automatic token refresh
Script requirements:
Output the token to standard output (stdout).
An exit code of 0 indicates success.
The script execution timeout is 30 seconds.
Configuration example:
{
  "apiKeyHelper": "/path/to/get-token.sh"
}
Example of obtaining a token from Vault:
#!/bin/bash
vault read -field=api_key secret/codebuddy/api-key
For detailed authentication configuration, see Settings Documentation - Environment Variables.

Access Control and Permissions

We support fine-grained permissions so that you can precisely specify which operations the agent is allowed to perform, such as running tests or running a linter, and which operations are not allowed, such as updating cloud infrastructure. These permission settings can be checked into version control and distributed to all developers in an organization, or they can be customized by individual developers.

Permission System

CodeBuddy Code uses a layered permission system to balance functionality and security:
Tool Type
Example
Approval Required
"Yes, Don't Ask Again" Behavior
Read-Only
File read, LS, Grep
No
N/A
Bash Command
Shell execution
Yes
Remember permanently by project directory and command
File Modification
Edit/write files
Yes
Valid until the session ends

Configuring Permissions

You can use /permissions to view and manage tool permissions for CodeBuddy Code. This UI lists all permission rules and the settings.json files they originate from.
The Allow rule permits CodeBuddy Code to use the specified tools without further manual approval.
The Ask rule prompts the user for confirmation when CodeBuddy Code attempts to use a specified tool. The Ask rule takes precedence over the allow rule.
The Deny rule prevents CodeBuddy Code from using specified tools. The Deny rule takes precedence over the allow and ask rules.
Additional directories extend CodeBuddy's file access to directories outside the initial working directory.
Default mode controls CodeBuddy's permission behavior when CodeBuddy encounters new requests.
Permission rules use the following format: Tool or Tool(optional-specifier)
A rule with only a tool name matches any use of that tool. For example, adding Bash to the allow rule list allows CodeBuddy Code to use the Bash tool without user approval.

Permission Mode

CodeBuddy Code supports multiple permission modes, which can be configured in permissions.defaultMode under settings or specified via --permission-mode. The common modes are as follows:
Mode
Description
default
Standard sequential approval mode
acceptEdits
Automatically approves file edits. Bash still requires approval.
auto
Use the classifier to automatically determine whether to allow actions that would originally trigger approval prompts.
dontAsk
Does not display permission prompts. Actions that are not pre-approved are denied directly.
plan
Plan mode. Primarily read and explore, and generate a plan before writing source code.
bypassPermissions
Skip all permission prompts (requires a secure environment).
For more complete mode semantics, switching methods, status bar prompts, and subagent inheritance rules, refer directly to Permission Modes.
Note:
The `bypassPermissions` mode should only be used in secure, isolated environments, such as Docker containers or VMs. Using this mode in production environments or on systems containing sensitive data may introduce security risks.
trustAll / trustedDirectories` are not alternatives to permission modes. These two fields only affect the directory trust authorization prompt at startup (a one-time popup asking whether to trust this directory and allow CodeBuddy to run in it), and are unrelated to whether approval prompts appear during tool execution.

To bypass tool approval, set permissions.defaultMode or use --permission-mode bypassPermissions / -y / --dangerously-skip-permissions.
Use trustAll: true or add the directory to trustedDirectories only to bypass the directory trust popup.
The two switches are independent. When bypassPermissions is enabled, the directory trust popup still appears normally, and vice versa.
Therefore, the statement "enable bypassPermissions + trustAll and nothing else needs to be configured" is inaccurate. The former controls tool approval, while the latter controls directory trust, and they address different confirmation prompts.

Working Directory

By default, CodeBuddy can access files in its startup directory. You can extend this access:
At startup: use the --add-dir <path> CLI parameter.
During a session: use the /add-dir slash command.
Persistent configuration: Add to additionalDirectories in the settings file.
Files in additional directories follow the same permission rules as the original working directory - they can be read without prompts, and file editing permissions follow the current permission mode.

Tool-Specific Permission Rules

Some tools support more fine-grained permission control:
Bash
Bash(npm run build) exactly matches the Bash command npm run build
Bash(npm run test:*) matches Bash commands that start with npm run test
Bash(curl http://site.com/:*) matches curl commands that start with curl http://site.com/
Note:
CodeBuddy Code can recognize shell operators (such as `&&`), so a prefix matching rule like `Bash(safe-cmd:*)` does not grant it permission to run the command `safe-cmd && other-cmd`.
Note:
Important limitations of Bash permission mode:
1. This tool uses prefix matching rather than regular expressions or glob patterns.
2. The wildcard :* is valid only at the end of a pattern and matches any subsequent content.
3. Patterns like Bash(curl http://github.com/:*) can be bypassed in multiple ways:
Options before the URL: curl -X GET http://github.com/... does not match.
Different protocol: curl https://github.com/... does not match.
Redirect: curl -L http://bit.ly/xyz (redirects to github)
Variable: URL=http://github.com && curl $URL does not match.
Extra space: curl http://github.com does not match.
To filter URLs more reliably, consider the following:
Use the WebFetch tool with the WebFetch(domain:github.com) permission.
Use CODEBUDDY.md to instruct CodeBuddy Code which curl patterns you allow.
Use hooks for custom permission validation.
Read & Edit
The Edit rule applies to all built-in tools that edit files. CodeBuddy will make every effort to apply the Read rule to all built-in tools that read files, such as Grep, Glob, and LS.
Both the Read and Edit rules follow the gitignore specification, which has four different pattern types:
Mode
Description
Example
Match
//path
An absolute path from the file system root directory
Read(//Users/alice/secrets/**)
/Users/alice/secrets/**
~/path
A path from the home directory
Read(~/Documents/*.pdf)
/Users/alice/Documents/*.pdf
/path
A path relative to the settings file
Edit(/src/**/*.ts)
<settings file path>/src/**/*.ts
path or ./path
A path relative to the current directory
Read(*.env)
<cwd>/*.env
Note:
A pattern like /Users/alice/file is not an absolute path - it is relative to your settings file. Use //Users/alice/file to indicate an absolute path.
Example:
Edit(/docs/**) - Edit in <project>/docs/ (not /docs/!).
Read(~/.zshrc) - Read the .zshrc in the home directory.
Edit(//tmp/scratch.txt) - Edit the absolute path /tmp/scratch.txt
Read(src/**) - Read from <current directory>/src/
WebFetch
WebFetch(domain:example.com) matches fetch requests to example.com.
MCP
mcp__puppeteer matches any tool provided by the puppeteer server (the name configured in CodeBuddy Code).
mcp__puppeteer__* is wildcard syntax that also matches all tools provided by the puppeteer server.
mcp__puppeteer__puppeteer_navigate matches the puppeteer_navigate tool provided by the puppeteer server.
Note:
To approve all tools from an MCP server, you can use either of the following formats:
✔ Use: mcp__github (approve all GitHub tools).
✔ Use: mcp__github__* (approve all GitHub tools, equivalent to the previous one).
To approve only specific tools, list each one:
✔ Use: mcp__github__get_issue
✔ Use: mcp__github__list_issues

Permission Configuration Examples

Basic permission configuration:
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "ask": [
      "WebFetch",
      "Bash(docker:*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Edit(**/*.env)",
      "Read(~/.ssh/**)"
    ]
  }
}
Security restriction configuration:
{
  "permissions": {
    "allow": [
      "Read",
      "Edit(src/**)",
      "Bash(git:status,git:diff)"
    ],
    "deny": [
      "Edit(**/*.env)",
      "Edit(**/*.key)",
      "Edit(**/*.pem)",
      "Bash(wget:*)",
      "Bash(curl:*)",
      "Read(/etc/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)"
    ],
    "defaultMode": "default"
  }
}

Using hooks for Additional Permission Control

CodeBuddy Code hooks provide a way to register custom shell commands that perform permission evaluation at runtime. When CodeBuddy Code makes a tool call, PreToolUse hooks run before the permission system, and the hook output can decide whether to approve or deny the tool call, replacing the permission system.
For details, see the Hooks documentation.

Setting Priorities

When multiple setting sources exist, they are applied in the following order (from highest to lowest priority):
1. Command line parameter.
2. Local project settings (.codebuddy/settings.local.json)
3. Shared project settings (.codebuddy/settings.json)
4. User settings (~/.codebuddy/settings.json)
This hierarchy ensures that project- and user-level flexibility is still allowed where appropriate.

Credential Management

CodeBuddy Code securely manages your authentication credentials:
Platform
Storage Location
macOS
Encrypted macOS Keychain
Linux
System keyring (GNOME Keyring, KWallet)
Windows
Windows Credential Manager
Dynamic credential retrieval: Use apiKeyHelper to configure a custom script to obtain tokens dynamically. For details, see the apiKeyHelper configuration.

Security Best Practices Tutorial

1. Principle of Least Privilege

Grant CodeBuddy Code only the minimum permissions required to complete the task:
{
  "permissions": {
    "allow": [
      "Read",
      "Edit(src/**/*.ts)",
      "Bash(npm:test,npm:build)"
    ],
    "deny": [
      "Edit(**/*.env)",
      "Bash(rm:*)",
      "Bash(sudo:*)"
    ]
  }
}

2. Protecting Sensitive Files

Always deny access to files that contain sensitive information:
{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(**/*.key)",
      "Edit(**/*.pem)"
    ]
  }
}

3. Using the Bash Sandbox

Enable the sandbox on supported platforms to isolate bash commands:
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"]
  }
}

4. Reviewing Permission Logs

Regularly review CodeBuddy Code permission usage to ensure compliance with security policies.

5. Sharing Team Configurations

Check team-level permission configurations into version control:
# Create a team shared configuration
.codebuddy/settings.json

# Add to .gitignore
.codebuddy/settings.local.json

FAQs

What Should I Do If API Key Authentication Fails?

This is the most common issue, usually because the CODEBUDDY_INTERNET_ENVIRONMENT environment variable is not configured or is configured incorrectly.
Troubleshooting Steps:
1. Confirm the edition you are using (Overseas Edition/China Edition/iOA Edition).
2. Check whether the environment variables are set correctly:
# Check the current configuration
echo $CODEBUDDY_API_KEY
echo $CODEBUDDY_INTERNET_ENVIRONMENT
3. Set the correct environment variables according to the version:
Version
CODEBUDDY_INTERNET_ENVIRONMENT
Overseas Edition
Not set
China Edition
internal
iOA Edition
ioa
Dedicated Edition
cloudhosted
Private Deployment
selfhosted
Common mistakes:
✖ China edition users forget to set CODEBUDDY_INTERNET_ENVIRONMENT=internal
✖ iOA edition users are set to internal instead of ioa
✖ Dedicated edition / self-hosted deployment users set only the environment variable and forget to specify the enterprise service address (the "Enterprise Domain Configuration" in the CLI or options.endpoint in the SDK), causing requests to still be sent to the default public network address.
✖ Environment variables take effect only in the current terminal and become invalid after a new terminal is opened. It is recommended to add them to the shell configuration file.

How to Temporarily Bypass Permissions?

Start CodeBuddy Code with the --permission-mode bypassPermissions flag:
codebuddy --permission-mode bypassPermissions
Note:
Use this option only in a secure, isolated environment.

How to Set Different Permissions for a Specific Project?

Create .codebuddy/settings.json in the project root directory:
{
  "permissions": {
    "allow": ["Project-specific permissions"]
  }
}

How to View the Current Permission Configuration?

Use the /permissions command to view all effective permission rules and their sources.

See Also

Settings Configuration - Learn about the complete configuration options.
Hooks Documentation - Use hooks for advanced permission control.
Bash Sandbox - Learn about the sandbox isolation feature.
MCP Integration - Configure MCP server permissions.
Previous Topic: Security OverviewNext Topic: Permission Mode

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation