demo
/
trax
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
trax/docs/API_KEY_MANAGEMENT.md

6.1 KiB
Raw Blame History

API Key Management System

Secure, centralized API key management for the Trax project and my-ai-projects workspace.

Quick Start

1. Initial Migration (One-Time Setup)

# Scan all projects and migrate keys to secure vault
cd apps/trax
python3 scripts/migrate_keys.py

# Or automatic mode (no prompts)
python3 scripts/migrate_keys.py --auto --conflict-resolution=newest

2. Daily Usage

# List all keys in vault
python3 scripts/key_vault.py list

# Get a specific key
python3 scripts/key_vault.py get ANTHROPIC_API_KEY

# Add a new key
python3 scripts/key_vault.py add MY_NEW_KEY --category=custom

# Export keys for Trax project
python3 scripts/key_vault.py export .env --project=trax

# Sync to all projects
python3 scripts/key_vault.py sync root trax youtube-summarizer

Features

🔐 Secure Storage

  • Encrypted vault using Fernet (symmetric encryption)
  • Password-protected master key with PBKDF2 derivation
  • File permissions automatically set to 0600 (owner-only)

🔍 Key Discovery

  • Automatic scanning of all project directories
  • Conflict detection when keys have different values
  • Missing key identification for standard requirements

📦 Project Integration

  • Export filtering - only export keys needed for each project
  • Batch sync to multiple project .env files
  • Validation ensures required keys are present

Architecture

Vault Structure

~/.my-ai-keys/                 # Default vault location
├── vault.enc                  # Encrypted key storage
├── metadata.json              # Key metadata (categories, timestamps)
└── .master                    # Master encryption key (protected)

Key Categories

  • ai - AI model API keys (Anthropic, OpenAI, DeepSeek, etc.)
  • services - External services (YouTube, Slack, GitHub, etc.)
  • oauth - OAuth credentials (Google Client ID/Secret)
  • database - Database connection strings
  • custom - Project-specific keys

Command Reference

Key Vault (key_vault.py)

# Add/Update Keys
python3 scripts/key_vault.py add KEY_NAME --value="secret" --category=ai
python3 scripts/key_vault.py add KEY_NAME  # Prompts for value securely

# Retrieve Keys
python3 scripts/key_vault.py get KEY_NAME
python3 scripts/key_vault.py list
python3 scripts/key_vault.py list --category=ai

# Import/Export
python3 scripts/key_vault.py import /path/to/.env
python3 scripts/key_vault.py export output.env
python3 scripts/key_vault.py export .env --project=trax

# Project Management
python3 scripts/key_vault.py validate trax
python3 scripts/key_vault.py sync root trax youtube-summarizer

# Key Rotation
python3 scripts/key_vault.py rotate ANTHROPIC_API_KEY

Migration Tool (migrate_keys.py)

# Full migration workflow
python3 scripts/migrate_keys.py

# Scan only (no migration)
python3 scripts/migrate_keys.py --scan-only

# Automatic migration
python3 scripts/migrate_keys.py --auto --conflict-resolution=newest

# Export migration report
python3 scripts/migrate_keys.py --export-report=migration_report.txt

Standard Keys

AI Models (Required for Trax v2+)

  • ANTHROPIC_API_KEY - Claude models (Task Master, Trax v2)
  • DEEPSEEK_API_KEY - Transcription enhancement (Trax v2)
  • PERPLEXITY_API_KEY - Research features (Task Master)

Services

  • YOUTUBE_API_KEY - YouTube Data API (optional)
  • GITHUB_TOKEN - GitHub integration
  • GITEA_TOKEN - Gitea CI/CD

Google OAuth (Optional)

  • GOOGLE_CLIENT_ID - OAuth client
  • GOOGLE_CLIENT_SECRET - OAuth secret

Security Best Practices

1. Vault Protection

  • Store vault in user home directory (~/.my-ai-keys/)
  • Never commit vault files to git
  • Use strong master password
  • Regularly rotate sensitive keys

2. Environment Files

  • Keep .env files in .gitignore
  • Use .env.example for templates
  • Set file permissions to 0600
  • Don't log or print full key values

3. Key Rotation

# Rotate a compromised key
python3 scripts/key_vault.py rotate COMPROMISED_KEY

# Re-sync to all projects
python3 scripts/key_vault.py sync root trax youtube-summarizer

Troubleshooting

Forgotten Master Password

The vault uses password-based encryption. If you forget the password:

  1. Keys cannot be recovered
  2. Create new vault: rm -rf ~/.my-ai-keys
  3. Re-run migration: python3 scripts/migrate_keys.py

Missing cryptography Package

# Install with pip
pip install cryptography

# Or with uv (in Trax)
uv pip install cryptography

Conflict Resolution

When keys have different values across projects:

  • newest - Use value from most recently modified file
  • ask - Prompt for each conflict (default)
  • skip - Don't migrate conflicting keys

Validation Errors

# Check which keys are missing
python3 scripts/key_vault.py validate trax

# Add missing keys
python3 scripts/key_vault.py add MISSING_KEY

# Re-export to project
python3 scripts/key_vault.py export .env --project=trax

Integration with Trax

Automatic Inheritance

Trax automatically loads keys from:

  1. Local .env file (highest priority)
  2. Parent ../../.env file (workspace root)
  3. Vault export via key_vault.py export

Config Access

from src.config import config

# Direct access
api_key = config.ANTHROPIC_API_KEY

# Check available services
services = config.get_available_ai_services()

# Validate required keys
config.validate_required_keys(["ANTHROPIC_API_KEY", "DEEPSEEK_API_KEY"])

Workspace-Wide Usage

The key vault can manage keys for all projects:

# Export to specific projects
python3 scripts/key_vault.py export ~/projects/my-ai-projects/.env --project=root
python3 scripts/key_vault.py export ~/projects/my-ai-projects/apps/youtube-summarizer/.env --project=youtube-summarizer

# Or use sync for batch operations
python3 scripts/key_vault.py sync root trax youtube-summarizer pdf-translator

Related Documentation