Authentication

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:

Platform	Storage Location
macOS	Keychain Access
Windows	Credential Manager
Linux	Secret Service (libsecret)

Environment Variables (CI/CD)

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

# Generic API key
export TDX_API_KEY=your-api-key-here

# Profile-specific API key (takes precedence when --profile is used)
export TDX_API_KEY_PRODUCTION=your-production-api-key
export TDX_API_KEY_MY_PROFILE=your-profile-api-key

Profile names are normalized for environment variable names: converted to uppercase with non-alphanumeric characters replaced by underscores. For example:

• --profile production → TDX_API_KEY_PRODUCTION
• --profile my-test-profile → TDX_API_KEY_MY_TEST_PROFILE

Deprecated: TD_API_KEY

The TD_API_KEY environment variable is deprecated. Please migrate to TDX_API_KEY. When TD_API_KEY is used, a deprecation warning will be shown.

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 a specific profile
tdx auth --profile production

Clear Credentials

Remove API key from the keychain:

# Clear default credentials
tdx auth clear

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

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.

Learn More

For advanced profile management including setting default databases, LLM projects, and session context, see Context Management.

Credential Resolution Priority

When tdx needs an API key, it checks sources in this order:

When --profile is specified:

1. TDX_API_KEY_<PROFILE> environment variable
2. Profile keychain credential
3. TDX_API_KEY environment variable
4. TD_API_KEY environment variable (deprecated)

When no profile:

1. TDX_API_KEY environment variable
2. Default keychain credential
3. TD_API_KEY environment variable (deprecated)

This ensures that profile-specific credentials take precedence over generic environment variables when using --profile.

Security Notes

• API keys are stored in the system keychain (encrypted by OS)
• Falls back to environment variables when keychain is unavailable