# Authentication

## Interactive Setup (Recommended)

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


```bash
# 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 Variable (Alternative)

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


```bash
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


```bash
# Check authentication status and validate
tdx auth

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

## Clear Credentials

Remove API key from the keychain:


```bash
# Clear default credentials
tdx auth clear

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

## Multi-Site Support

tdx supports multiple Treasure Data regions:

| Site | Region | API Endpoint |
|  --- | --- | --- |
| `us01` (default) | US | api.treasuredata.com |
| `jp01` | Japan | api.treasuredata.co.jp |
| `eu01` | Europe | api.eu01.treasuredata.com |
| `ap02` | Asia Pacific | api.ap02.treasuredata.com |


Switch sites with the `--site` flag:


```bash
tdx databases --site jp01
```

## Profile-Based Authentication

For managing multiple environments, use profiles:


```bash
# 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