How do I rotate an API key?

Rotating API keys regularly is an important security practice. Here's how to safely rotate your keys without disrupting your service.

Why rotate API keys?

• Security best practice: Limits exposure if a key is ever compromised

• Team member changes: When developers leave or change roles

• Suspected compromise: If you believe a key may have been exposed

• Compliance: Some security policies require periodic key rotation

• Environment changes: When migrating infrastructure or refactoring

Standard rotation process (zero downtime)

Step 1: Create a new key

1. Log in to Settings → API

2. Click "Create new API key"

3. Name it descriptively (e.g., "Production Web v2")

4. Copy the new key immediately - it's shown only once

5. Store it securely

Step 2: Update your application

• Deploy the new key to your application (environment variables, secrets manager, etc.)

• Restart your application to load the new key

• Verify the new key is working correctly

• Monitor for any errors

Step 3: Monitor the transition

• Keep both keys active temporarily

• Check Settings → API to see "Last used" dates

• Wait until old key shows no recent activity

• Ensure all instances/services have switched to the new key

Step 4: Delete the old key

• Once confirmed the old key is no longer in use

• Delete or deactivate the old key in Settings → API

• Document the rotation for your records

Quick rotation process (if compromised)

If a key is definitely compromised and you need to act immediately:

1. Delete the compromised key first in Settings → API

2. Create a new replacement key

3. Quickly deploy the new key to all applications

4. Accept brief downtime to prevent unauthorized access

5. Monitor usage logs for any suspicious activity

6. Contact support if needed

Multi-environment rotation strategy

For production systems, use a phased approach:

Week 1: Development

• Create and deploy new key to dev environment

• Test thoroughly

Week 2: Staging

• Deploy new key to staging

• Run integration tests

• Monitor for issues

Week 3: Production

• Deploy new key to production during low-traffic period

• Monitor closely

• Keep old key active for 24-48 hours as fallback

Week 4: Cleanup

• Verify old key shows no activity

• Delete old key

• Update documentation

Automation example

Script to help verify key rotation is complete:

#!/bin/bash
# check-api-key.sh
OLD_KEY="sk_live_OLD123..."
NEW_KEY="sk_live_NEW789..."
echo "Testing old key..."
OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Testing new key..."
NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $NEW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Old key status: ${OLD_RESPONSE: -3}"
echo "New key status: ${NEW_RESPONSE: -3}"
if [ "${NEW_RESPONSE: -3}" == "200" ]; then
  echo "✅ New key is working!"
else
  echo "❌ New key failed!"
fi

Best practices

• Rotate regularly: Every 90 days for production keys

• Document rotations: Keep a log of when keys were rotated and why

• Test before deleting: Always verify the new key works before removing the old one

• Use multiple keys: Separate keys per environment make rotation easier

• Automate where possible: Use secrets management tools that support automatic rotation

After rotation checklist

Confirm these items after rotating:

• ✅ All production instances using new key

• ✅ All staging/dev environments updated (if using same key)

• ✅ Environment variables updated

• ✅ CI/CD secrets updated

• ✅ Documentation updated

• ✅ Team members notified

• ✅ Old key deleted

• ✅ Rotation logged for audit purposes