# Dynamic Secrets Guide\n\nThis guide covers generating and managing temporary credentials (dynamic secrets) instead of using static secrets. See the Quick Reference section\nbelow for fast lookup.\n\n## Quick Reference\n\n**Quick Start**: Generate temporary credentials instead of using static secrets\n\n### Quick Commands\n\n#### Generate AWS Credentials (1 hour)\n\n```\nsecrets generate aws --role deploy --workspace prod --purpose "deployment"\n```\n\n#### Generate SSH Key (2 hours)\n\n```\nsecrets generate ssh --ttl 2 --workspace dev --purpose "server access"\n```\n\n#### Generate UpCloud Subaccount (2 hours)\n\n```\nsecrets generate upcloud --workspace staging --purpose "testing"\n```\n\n#### List Active Secrets\n\n```\nsecrets list\n```\n\n#### Revoke Secret\n\n```\nsecrets revoke <secret-id> --reason "no longer needed"\n```\n\n#### View Statistics\n\n```\nsecrets stats\n```\n\n---\n\n## Secret Types\n\n| Type | TTL Range | Renewable | Use Case |\n| ------ | ----------- | ----------- | ---------- |\n| AWS STS | 15 min - 12 h | ✅ Yes | Cloud resource provisioning |\n| SSH Keys | 10 min - 24 h | ❌ No | Temporary server access |\n| UpCloud | 30 min - 8 h | ❌ No | UpCloud API operations |\n| Vault | 5 min - 24 h | ✅ Yes | Any Vault-backed secret |\n\n---\n\n## REST API Endpoints\n\n**Base URL**: `http://localhost:9090/api/v1/secrets`\n\n```\n# Generate secret\nPOST /generate\n\n# Get secret\nGET /{id}\n\n# Revoke secret\nPOST /{id}/revoke\n\n# Renew secret\nPOST /{id}/renew\n\n# List secrets\nGET /list\n\n# List expiring\nGET /expiring\n\n# Statistics\nGET /stats\n```\n\n---\n\n## AWS STS Example\n\n```\n# Generate\nlet creds = secrets generate aws `\n    --role deploy `\n    --region us-west-2 `\n    --workspace prod `\n    --purpose "Deploy servers"\n\n# Export to environment\nexport-env {\n    AWS_ACCESS_KEY_ID: ($creds.credentials.access_key_id)\n    AWS_SECRET_ACCESS_KEY: ($creds.credentials.secret_access_key)\n    AWS_SESSION_TOKEN: ($creds.credentials.session_token)\n}\n\n# Use credentials\nprovisioning server create\n\n# Cleanup\nsecrets revoke ($creds.id) --reason "done"\n```\n\n---\n\n## SSH Key Example\n\n```\n# Generate\nlet key = secrets generate ssh `\n    --ttl 4 `\n    --workspace dev `\n    --purpose "Debug issue"\n\n# Save key\n$key.credentials.private_key | save ~/.ssh/temp_key\nchmod 600 ~/.ssh/temp_key\n\n# Use key\nssh -i ~/.ssh/temp_key user@server\n\n# Cleanup\nrm ~/.ssh/temp_key\nsecrets revoke ($key.id) --reason "fixed"\n```\n\n---\n\n## Configuration\n\n**File**: `provisioning/platform/orchestrator/config.defaults.toml`\n\n```\n[secrets]\ndefault_ttl_hours = 1\nmax_ttl_hours = 12\nauto_revoke_on_expiry = true\nwarning_threshold_minutes = 5\n\naws_account_id = "123456789012"\naws_default_region = "us-east-1"\n\nupcloud_username = "${UPCLOUD_USER}"\nupcloud_password = "${UPCLOUD_PASS}"\n```\n\n---\n\n## Troubleshooting\n\n### "Provider not found"\n\n→ Check service initialization\n\n### "TTL exceeds maximum"\n\n→ Reduce TTL or configure higher max\n\n### "Secret not renewable"\n\n→ Generate new secret instead\n\n### "Missing required parameter"\n\n→ Check provider requirements (for example, AWS needs 'role')\n\n---\n\n## Security Features\n\n- ✅ No static credentials stored\n- ✅ Automatic expiration (1-12 hours)\n- ✅ Auto-revocation on expiry\n- ✅ Full audit trail\n- ✅ Memory-only storage\n- ✅ TLS in transit\n\n---\n\n## Support\n\n**Orchestrator logs**: `provisioning/platform/orchestrator/data/orchestrator.log`\n\n**Debug secrets**: `secrets list | where is_expired == true`
