​

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 {{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

​

Naming Convention

[service]_[environment]_[type]

stripe_production_api_key
stripe_staging_api_key
stripe_development_api_key

database_prod_password
database_staging_password
database_dev_password

​

Configure Routes

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

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

​

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 {{stripe_api_key}}",
  "X-Partner-Key": "{{partner_api_key}}",
  "X-Database": "{{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