Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Interactive Setup (Recommended)

The easiest way to set up authentication is the interactive setup command:

# Interactive setup with site selection
tdx auth setup

# Set up profile-specific authentication
tdx auth setup --profile production

The setup command will:

• Guide you through site selection
• Securely prompt for your API key
• Validate the API key before saving
• Save to your system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service)

Credential Storage

System Keychain (Default)

API keys are stored securely in your operating system's keychain:

Environment Variable (Alternative)

For CI/CD pipelines or headless environments where keychain is unavailable:

export TD_API_KEY=your-api-key-here/...

Legacy .env Files

If you have existing .env files from previous versions, they will be automatically migrated to the keychain on first use. After migration, the .env file is removed.

Check Authentication Status

# Check authentication status and validate
tdx auth

# Check status for specific site
tdx auth --site jp01

Clear Credentials

Remove API key from the keychain:

# Clear default credentials
tdx auth clear

# Clear profile-specific credentials
tdx auth clear --profile production

Multi-Site Support

tdx supports multiple Treasure Data regions:

Switch sites with the --site flag:

tdx databases --site jp01

Profile-Based Authentication

For managing multiple environments, use profiles:

# Set up production profile
tdx auth setup --profile production

# Set up development profile
tdx auth setup --profile development

# Use a profile for commands
tdx --profile production databases

# Switch default profile
tdx use profile production

Each profile stores its API key separately in the keychain, keyed by profile name.

Security Notes

• API keys are stored in the system keychain (encrypted by OS)
• Falls back to environment variables when keychain is unavailable
• NO support for project-local credential files (prevents accidental commits)
• API key validation is performed server-side by the Treasure Data API
• In-memory credential cache (5-minute TTL) reduces keychain lookups