Identity and Access Management ​

Learn how to configure user authentication, authorization, and access control for CodeBuddy Code in your organization.

Authentication Methods ​

Quick Start ​

Choose an authentication method based on your scenario:

ScenarioRecommended MethodHow to Get Credentials
Individual DeveloperCODEBUDDY_API_KEYGet API Key from platform
Enterprise/Team (OAuth Integration)apiKeyHelperCreate app to get Client ID/Secret
CI/CD with existing OAuth tokenCODEBUDDY_AUTH_TOKENUse existing token directly
Third-party Model ServiceCODEBUDDY_API_KEY + BASE_URLGet from third-party provider

When multiple authentication methods are configured, they take effect in the following priority: CODEBUDDY_AUTH_TOKEN > apiKeyHelper > CODEBUDDY_API_KEY

Individual Users: Get API Key ​

Suitable for individual developers to get started quickly using the model services provided by the CodeBuddy platform.

Step 1: Get API Key

Visit the corresponding platform to get your API Key:

VersionURL
Internationalhttps://www.codebuddy.ai/profile/keys
Chinahttps://copilot.tencent.com/profile/
iOAhttps://tencent.sso.copilot.tencent.com/profile/keys

Step 2: Configure Environment Variables

Warning: You must correctly configure the CODEBUDDY_INTERNET_ENVIRONMENT environment variable!

This is the most commonly missed configuration item. If not set or set incorrectly, it will cause authentication failure or connection to the wrong service endpoint.

Configure the corresponding environment variables based on your version:

International Version:

bash
export CODEBUDDY_API_KEY="your-api-key"
# International version does not need to set CODEBUDDY_INTERNET_ENVIRONMENT (default value)

China Version:

bash
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

iOA Version:

bash
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_INTERNET_ENVIRONMENT=ioa
VersionCODEBUDDY_INTERNET_ENVIRONMENT ValueDescription
InternationalNot set (or public)Default value, connects to international services
ChinainternalConnects to China region services
iOAioaConnects to Tencent iOA intranet services

Tip for Persistent Configuration: Add environment variables to ~/.bashrc, ~/.zshrc, or your shell configuration file to avoid setting them manually each time.

bash
# Add to ~/.zshrc or ~/.bashrc
echo 'export CODEBUDDY_API_KEY="your-api-key"' >> ~/.zshrc
echo 'export CODEBUDDY_INTERNET_ENVIRONMENT=internal' >> ~/.zshrc  # China version
source ~/.zshrc

Step 3: Start Using

bash
codebuddy

Enterprise Users: OAuth Authentication ​

Suitable for enterprise/team integration, obtaining tokens via OAuth 2.0.

Currently only introducing the Client Credentials authorization method, suitable for server-side applications and CI/CD scenarios.

Step 1: Create Application, Get Client ID and Secret

Refer to the Enterprise Developer Quick Start to complete:

  1. Create an enterprise application
  2. Get Client ID and Client Secret

Step 2: Create a Script to Get Token

bash
#!/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 project .codebuddy/settings.json:

json
{
  "apiKeyHelper": "/path/to/get-oauth-token.sh"
}

After configuration, you can use the codebuddy command.

Tokens obtained by apiKeyHelper are cached for 5 minutes by default. You can adjust this via the CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS environment variable (in milliseconds).

Third-Party Model Services ​

Suitable for using third-party model services like OpenRouter.

bash
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 Key, suitable for most scenarios.

FeatureDescription
Environment VariableCODEBUDDY_API_KEY
Auth TypeAPI Key (X-Api-Key header)
Use CasesPersonal development, third-party model services

Warning: When using API Key, you must also configure the CODEBUDDY_INTERNET_ENVIRONMENT environment variable!

VersionConfiguration Value
InternationalNot set (default)
Chinainternal
iOAioa
bash
# International version
export CODEBUDDY_API_KEY="your-api-key"

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

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

CODEBUDDY_AUTH_TOKEN ​

Pre-obtained OAuth Bearer Token, suitable for CI/CD or scenarios with existing tokens.

FeatureDescription
Environment VariableCODEBUDDY_AUTH_TOKEN
Auth TypeBearer Token (Authorization header)
Use CasesCI/CD automation, existing OAuth token
bash
export CODEBUDDY_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIs..."

Can also be configured in settings.json:

json
{
  "env": {
    "CODEBUDDY_AUTH_TOKEN": "your-oauth-token"
  }
}

apiKeyHelper ​

Dynamically obtain tokens via script, suitable for OAuth integration or scenarios requiring periodic token refresh.

FeatureDescription
ConfigurationapiKeyHelper field in settings.json
Auth TypeBearer Token (returned by script)
CachingDefault 5 minutes, configurable via CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS
Use CasesOAuth Client Credentials, Vault integration, automatic token refresh

Script Requirements:

  • Output the token to standard output (stdout)
  • Exit with code 0 to indicate success
  • Script execution timeout is 30 seconds

Configuration Example:

json
{
  "apiKeyHelper": "/path/to/get-token.sh"
}

Example of Getting Token from Vault:

bash
#!/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 you can precisely specify what the agent is allowed to do (e.g., run tests, run linters) and not allowed to do (e.g., update cloud infrastructure). These permission settings can be checked into version control and distributed to all developers in your organization, or customized by individual developers.

Permission System ​

CodeBuddy Code uses a hierarchical permission system to balance functionality and security:

Tool TypeExamplesRequires Approval"Yes, don't ask again" Behavior
Read-onlyFile reading, LS, GrepNoN/A
Bash commandsShell executionYesPermanently remembered by project directory and command
File modificationsEdit/Write filesYesEffective until session ends

Configuring Permissions ​

You can use /permissions to view and manage CodeBuddy Code's tool permissions. This UI lists all permission rules and the settings.json files they come from.

  • Allow rules will allow CodeBuddy Code to use specified tools without further manual approval.
  • Ask rules will prompt for user confirmation when CodeBuddy Code attempts to use specified tools. Ask rules take precedence over allow rules.
  • Deny rules will block CodeBuddy Code from using specified tools. Deny rules take precedence over allow and ask rules.
  • Additional directories extend CodeBuddy's file access to directories beyond the initial working directory.
  • Default mode controls CodeBuddy's permission behavior when encountering new requests.

Permission rules use the format: Tool or Tool(optional-specifier)

Rules with only the tool name match any use of that tool. For example, adding Bash to the allow rules list will allow CodeBuddy Code to use the Bash tool without user approval.

Permission Modes ​

CodeBuddy Code supports several permission modes, which can be set as defaultMode in the settings file:

ModeDescription
defaultStandard behavior - prompts for permission on first use of each tool
acceptEditsAutomatically accepts file edit permissions for the session
planPlan mode - CodeBuddy can analyze but not modify files or execute commands
bypassPermissionsSkips all permission prompts (requires secure environment - see warning below)

WARNING

`bypassPermissions` mode should only be used in secure, isolated environments, such as Docker containers or VMs. Using this mode on production environments or systems with sensitive data may pose security risks.

Working Directory ​

By default, CodeBuddy can access files in the directory where it's launched. You can extend this access:

  • At startup: Use the --add-dir <path> CLI parameter
  • During 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 edit 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 starting with npm run test
  • Bash(curl http://site.com/:*) matches curl commands starting with curl http://site.com/

TIP

CodeBuddy Code recognizes shell operators (like `&&`), so prefix matching rules like `Bash(safe-cmd:*)` won't grant it permission to run commands like `safe-cmd && other-cmd`

WARNING

Important limitations of Bash permission patterns:
  1. This tool uses prefix matching, not regular expressions or glob patterns
  2. The wildcard :* only works at the end of the pattern to match any subsequent content
  3. Patterns like Bash(curl http://github.com/:*) can be bypassed in multiple ways:
    • Options before URL: curl -X GET http://github.com/... doesn't match
    • Different protocol: curl https://github.com/... doesn't match
    • Redirects: curl -L http://bit.ly/xyz (redirects to github)
    • Variables: URL=http://github.com && curl $URL doesn't match
    • Extra spaces: curl http://github.com doesn't match

For more reliable URL filtering, consider:

  • Using the WebFetch tool with WebFetch(domain:github.com) permission
  • Instructing CodeBuddy Code via CODEBUDDY.md about allowed curl patterns
  • Using hooks for custom permission validation

Read & Edit

Edit rules apply to all built-in tools that edit files. CodeBuddy will try its best to apply Read rules to all built-in tools that read files, like Grep, Glob, and LS.

Read and Edit rules both follow the gitignore specification, with four different pattern types:

PatternMeaningExampleMatches
//pathAbsolute path from filesystem rootRead(//Users/alice/secrets/**)/Users/alice/secrets/**
~/pathPath from home directoryRead(~/Documents/*.pdf)/Users/alice/Documents/*.pdf
/pathRelative to settings file pathEdit(/src/**/*.ts)<settings file path>/src/**/*.ts
path or ./pathRelative to current directoryRead(*.env)<cwd>/*.env

WARNING

Patterns like `/Users/alice/file` are not absolute paths - they're relative to your settings file! Use `//Users/alice/file` for absolute paths.

Examples:

  • Edit(/docs/**) - Edit in <project>/docs/ (not /docs/!)
  • Read(~/.zshrc) - Read home directory's .zshrc
  • Edit(//tmp/scratch.txt) - Edit 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 (name configured in CodeBuddy Code)
  • mcp__puppeteer__* wildcard syntax, also matches all tools from the puppeteer server
  • mcp__puppeteer__puppeteer_navigate matches the puppeteer_navigate tool provided by the puppeteer server

TIP

To approve all tools from an MCP server, you can use either format:
  • Use: mcp__github (approves all GitHub tools)
  • Use: mcp__github__* (approves all GitHub tools, equivalent to the above)

To approve only specific tools, list each one:

  • Use: mcp__github__get_issue
  • Use: mcp__github__list_issues

Permission Configuration Examples ​

Basic Permission Configuration:

json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git:*)",
      "Bash(npm:*)"
    ],
    "ask": [
      "WebFetch",
      "Bash(docker:*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "Edit(**/*.env)",
      "Read(~/.ssh/**)"
    ]
  }
}

Security-Restricted Configuration:

json
{
  "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 for runtime permission evaluation. When CodeBuddy Code makes a tool call, PreToolUse hooks run before the permission system, and hook output can decide to approve or deny the tool call instead of the permission system.

See Hooks Documentation for details.

Settings Priority ​

When multiple settings sources exist, they are applied in the following order (from highest to lowest priority):

  1. Command line arguments
  2. Local project settings (.codebuddy/settings.local.json)
  3. Shared project settings (.codebuddy/settings.json)
  4. User settings (~/.codebuddy/settings.json)

This hierarchy ensures flexibility at project and user levels where appropriate.

Credential Management ​

CodeBuddy Code securely manages your authentication credentials:

PlatformStorage Location
macOSEncrypted macOS Keychain
LinuxSystem keyring (GNOME Keyring, KWallet)
WindowsWindows Credential Manager

Dynamic Credential Retrieval: Use apiKeyHelper to configure custom scripts for dynamic token retrieval. See apiKeyHelper Configuration for details.

Security Best Practices ​

1. Principle of Least Privilege ​

Only grant CodeBuddy Code the minimum permissions needed to complete tasks:

json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit(src/**/*.ts)",
      "Bash(npm:test,npm:build)"
    ],
    "deny": [
      "Edit(**/*.env)",
      "Bash(rm:*)",
      "Bash(sudo:*)"
    ]
  }
}

2. Protect Sensitive Files ​

Always deny access to files containing sensitive information:

json
{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(secrets/**)",
      "Read(~/.ssh/**)",
      "Read(~/.aws/**)",
      "Edit(**/*.key)",
      "Edit(**/*.pem)"
    ]
  }
}

3. Use Bash Sandbox ​

Enable sandboxing on supported platforms to isolate bash commands:

json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"]
  }
}

See Bash Sandbox Documentation for details.

4. Review Permission Logs ​

Regularly check CodeBuddy Code's permission usage to ensure compliance with security policies.

5. Team Configuration Sharing ​

Check team-level permission configurations into version control:

bash
# Create team shared configuration
.codebuddy/settings.json

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

Common Questions ​

What if API Key authentication fails? ​

This is the most common issue, usually caused by not configuring or incorrectly configuring the CODEBUDDY_INTERNET_ENVIRONMENT environment variable.

Troubleshooting Steps:

  1. Confirm which version you're using (International/China/iOA)
  2. Check if environment variables are correctly set:
bash
# Check current configuration
echo $CODEBUDDY_API_KEY
echo $CODEBUDDY_INTERNET_ENVIRONMENT
  1. Set the correct environment variables based on your version:
VersionCODEBUDDY_INTERNET_ENVIRONMENT
InternationalNot set or public
Chinainternal
iOAioa

Common Errors:

  • China version users forget to set CODEBUDDY_INTERNET_ENVIRONMENT=internal
  • iOA version users set it to internal instead of ioa
  • Environment variables only take effect in the current terminal and are lost when opening a new terminal (recommend adding to shell configuration file)

How do I temporarily bypass permissions? ​

Start CodeBuddy Code with --permission-mode bypassPermissions:

bash
codebuddy --permission-mode bypassPermissions

WARNING

Only use this option in secure, isolated environments!

How do I set different permissions for specific projects? ​

Create .codebuddy/settings.json in the project root directory:

json
{
  "permissions": {
    "allow": ["project-specific permissions"]
  }
}

How do I view current permission configuration? ​

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

See Also ​

Ensure CodeBuddy Code works within security boundaries through proper permission configuration