​

Secret Rotation and Management

​

Why Rotate Secrets?

• Limit blast radius if compromised
• Meet compliance requirements (PCI DSS, SOC 2)
• Best practice for production systems

• Critical secrets (production API keys): Every 30 days
• Standard secrets: Every 90 days
• Database passwords: Every 90 days
• OAuth tokens: When revoked by provider

​

Safe Rotation Process

​

Step-by-Step

Old: stripe_api_key
New: stripe_api_key_v2

{
  "Authorization": "Bearer {{secret:stripe_api_key_v2}}"
}

​

Why This Works

• Zero downtime
• Easy rollback (keep old secret temporarily)
• Clear audit trail

​

What NOT to Do

• You can’t update values (by design)
• Must create new secret

• Keep old secret for 48 hours
• Allows rollback if issues

​

Environment-Specific Secrets

​

Approach 1: Environment Configurations (Recommended)

Secret: stripe_api_key

Environments:
  production:  sk_live_abc123xyz789
  staging:     sk_test_staging_456def
  development: sk_test_dev_789ghi

1. Create a secret: stripe_api_key
2. In the secret detail page, select environment from dropdown
3. Add value for each environment:
   • Switch to “production” → Enter live key
   • Switch to “staging” → Enter test key
   • Switch to “development” → Enter dev key

{
  "Authorization": "Bearer {{secret:stripe_api_key}}"
}

• Route in “production” environment → Uses production value
• Route in “staging” environment → Uses staging value
• Hard fail if missing: Route returns error if secret lacks the environment value
• No fallbacks or defaults (prevents accidental production key usage in dev)

• ✅ One secret name across all environments
• ✅ Impossible to accidentally use wrong key
• ✅ Clear environment isolation
• ✅ Simplified route configuration

​

Approach 2: Naming Convention (Legacy)

Secrets:
  stripe_production_api_key
  stripe_staging_api_key
  stripe_development_api_key

{
  "Authorization": "Bearer {{secret:stripe_production_api_key}}"
}

{
  "Authorization": "Bearer {{secret:stripe_staging_api_key}}"
}

• ❌ Must update route config when changing environments
• ❌ Possible to reference wrong secret in wrong environment
• ❌ More secrets to manage

​

Comparison

​

Organization Strategies

​

Group by Service

stripe_api_key
stripe_webhook_secret
stripe_publishable_key

sendgrid_api_key
sendgrid_webhook_key

aws_access_key_id
aws_secret_access_key
aws_region

​

Group by Environment

production_stripe_key
production_sendgrid_key
production_database_url

staging_stripe_key
staging_sendgrid_key
staging_database_url

​

Multiple Secrets in One Route

{
  "Authorization": "Bearer {{secret:stripe_api_key}}",
  "X-Partner-Key": "{{secret:partner_api_key}}",
  "X-Database": "{{secret:database_url}}"
}

​

Monitoring Secret Usage

​

Track Usage

• Last Used - When secret was last injected
• Associated Routes - Which routes use this secret

​

Find Unused Secrets

• Last used > 30 days ago
• No associated routes
• Test/temporary secrets

​

Set Up Alerts

• Secret not used in 30+ days
• Multiple failed auth attempts (might indicate compromised key)
• Secret approaching rotation date

​

Common Patterns

​

API Key Rotation

1. Generate new key from provider (Stripe, SendGrid, etc)
2. Create secret: service_key_v2
3. Update routes to use v2
4. Test thoroughly
5. Delete old secret after 48h

​

Database Password Rotation

1. Create new password in database
2. Create secret: db_password_v2
3. Update routes to use v2
4. Test all database connections
5. Remove old password from database
6. Delete old secret

​

OAuth Token Refresh

1. Refresh token via OAuth flow
2. Create secret: service_oauth_token_v2
3. Update routes
4. Test authentication
5. Revoke old token with provider
6. Delete old secret

​

Troubleshooting

• Verify new secret value is correct
• Check all routes were updated
• Look for cached old values
• Roll back to old secret if needed

• Check spelling (case-sensitive)
• Verify secret exists in Secrets page
• Confirm route is using correct name

• New secret value might be wrong
• API key might be expired/revoked
• Test secret value directly with provider

​

Rotation Checklist

• Document which routes use this secret
• Generate new credential from provider
• Create new secret with v2 suffix
• Update all routes in staging
• Test thoroughly in staging
• Update routes in production
• Monitor for 48 hours
• Verify no errors
• Delete old secret
• Update documentation
• Schedule next rotation (calendar)

​

Next Steps

• Set up environments for per-env secrets
• Learn about securing your routes
• Configure monitoring and alerting