Credential Management¶

How Dango stores and manages API keys and credentials.

Overview¶

Dango needs credentials to connect to data sources:

• API keys (Stripe, etc.)
• OAuth tokens (Google, Facebook)
• Database passwords
• Custom source credentials

Storage Mechanisms¶

secrets.toml (Primary Storage)¶

Dango stores all credentials in .dlt/secrets.toml:

# .dlt/secrets.toml
[sources.stripe]
api_key = "sk_live_xxx"

[sources.my_database]
password = "database_password"

Credential Types¶

API Keys¶

For services like Stripe:

# Add via wizard (stored in secrets.toml)
dango source add stripe
# Enter API key when prompted

# Or configure manually in secrets.toml

# .dlt/secrets.toml
[sources.stripe]
stripe_secret_key = "sk_live_xxx"

OAuth Tokens¶

For Google, Facebook, etc.:

# Authenticate via browser
dango auth google_sheets

OAuth tokens are stored in .dlt/secrets.toml under the source's credentials section:

# .dlt/secrets.toml (auto-generated by dango auth)
[sources.google_sheets.credentials]
client_id = "xxx.apps.googleusercontent.com"
client_secret = "xxx"
refresh_token = "1//xxx"

Database Credentials¶

For database connections:

# .dlt/secrets.toml
[sources.my_postgres]
host = "localhost"
port = 5432
database = "mydb"
username = "user"
password = "password"

Environment Variables¶

Using Environment Variables¶

Reference environment variables in secrets.toml:

# .dlt/secrets.toml
[sources.stripe]
stripe_secret_key = "${STRIPE_API_KEY}"

Set the variable:

export STRIPE_API_KEY="sk_live_xxx"

$env:STRIPE_API_KEY = "sk_live_xxx"

.env Files¶

For development, use a .env file:

# .env (DO NOT COMMIT)
STRIPE_API_KEY=sk_live_xxx
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com

Load with:

source .env  # Linux/macOS
dango sync

Or use a tool like direnv for automatic loading.

Credential Lifecycle¶

Adding Credentials¶

# Via wizard (recommended)
dango source add stripe

# Manually edit secrets.toml
nano .dlt/secrets.toml

Viewing Credentials¶

Credentials are masked in Dango output:

dango config show
# API Key: sk_live_***************

To verify OAuth credentials exist:

dango auth status

Updating Credentials¶

# Re-run auth for OAuth
dango auth google_sheets

# Edit secrets.toml for API keys
nano .dlt/secrets.toml

Removing Credentials¶

# Remove OAuth token
dango auth remove google_sheets

# Remove from secrets.toml manually
nano .dlt/secrets.toml

Credential Rotation¶

When to Rotate¶

Rotate credentials when: - Credential may have been exposed - Employee leaves the team - Regular security policy (e.g., quarterly) - Service provider recommends

Rotation Process¶

1. Generate new credential in the service provider's dashboard
2. Update Dango with new credential
3. Test with dango sync --source affected_source
4. Revoke old credential in the service provider

# Update credential
nano .dlt/secrets.toml

# Test
dango sync --source stripe_payments

# If successful, revoke old key in Stripe dashboard

Secrets.toml Structure¶

Full Example¶

# .dlt/secrets.toml

# Stripe API
[sources.stripe]
stripe_secret_key = "sk_live_xxx"

# Google OAuth (manual setup)
[sources.google_sheets]
client_id = "xxx.apps.googleusercontent.com"
client_secret = "xxx"

# Database connection
[sources.postgres_db]
host = "localhost"
port = 5432
database = "analytics"
username = "dango_user"
password = "secure_password"

# Custom API
[sources.my_api]
api_key = "xxx"
base_url = "https://api.example.com"

# Using environment variables
[sources.production]
api_key = "${PROD_API_KEY}"

Organizing Secrets¶

Group by source name (must match sources.yml):

# .dango/sources.yml
sources:
  - name: stripe_payments  # <- This name
    type: stripe

# .dlt/secrets.toml
[sources.stripe_payments]  # <- Must match
stripe_secret_key = "sk_live_xxx"

System Keyring (Optional Encryption)¶

Dango can optionally use the system keyring to store an encryption key that protects sensitive tokens in secrets.toml:

Keyring Troubleshooting¶

Security Considerations¶

Plaintext Risks¶

secrets.toml stores credentials in plaintext: - Readable by anyone with file access - Visible in backups - Could be accidentally committed

Mitigations: - Proper file permissions: chmod 600 .dlt/secrets.toml - Always use .gitignore - Encrypt backups

Credential Exposure Signs¶

Watch for: - Unexpected API usage spikes - Unknown IP addresses in service logs - Credentials in git history - Credentials in error logs

If Credentials Are Exposed¶

1. Immediately revoke the compromised credential
2. Generate new credential
3. Update Dango configuration
4. Audit for unauthorized access
5. Review how exposure occurred

Next Steps¶

• OAuth Tokens - OAuth-specific security
• Best Practices - Security recommendations
• Git Workflows - Avoiding commits of secrets