API Key Rotation

Why Rotate Keys?

Regular key rotation provides several important security benefits:

• Limit exposure window - If a key is compromised, rotation ensures the attacker's access is time-limited
• Reduce risk from leaks - Keys may inadvertently appear in logs, error messages, or version control history
• Meet compliance requirements - Many security frameworks (SOC 2, PCI-DSS, ISO 27001) require periodic credential rotation
• Revoke access cleanly - When team members leave or applications are decommissioned, rotating ensures old keys stop working
• Audit trail clarity - Fresh keys make it easier to track when and where credentials were provisioned

How to Rotate Your API Key

You can rotate your primary API key through the dashboard:

1. Navigate to API Keys in your dashboard
2. Click the Rotate Key button on your primary API key
3. If you have a Pro or Mega plan, optionally select an expiration period for the new key
4. Confirm by clicking Rotate Key
5. Copy your new API key and update all your applications

What Happens During Rotation

1. A new API key is generated with the apv_ prefix
2. The new key is immediately active and ready to use
3. The old key is permanently invalidated
4. Your sub-keys remain unaffected (they continue working)
5. Your subscription, usage history, and settings are preserved

Key Expiration

Pro and Mega plans include the ability to set automatic key expiration. When you rotate your key, you can choose when it should expire:

Expiration Indicators

Your dashboard shows the expiration status of your API key:

• Never - Key does not have an expiration date
• Date with days remaining - Shows when the key will expire
• Expiring soon (yellow) - Less than 14 days until expiration
• Expired (red) - Key has expired and needs rotation

What Happens When a Key Expires

When your API key reaches its expiration date:

• All API requests using that key receive a 401 Unauthorized error
• The error message indicates the key has expired
• You must rotate to a new key to restore access
• Sub-keys continue working (they don't inherit expiration from the primary key)

{
  "status": "error",
  "error": "API key has expired. Please rotate your key in the dashboard.",
  "data": null
}

Rotation Strategies

How you handle key rotation depends on your application architecture and deployment process.

Zero-Downtime Rotation

For production systems that can't tolerate downtime:

1. Use sub-keys - Create a sub-key for each application or service
2. Rotate one at a time - When rotating, create a new sub-key, deploy it, then delete the old one
3. Stagger rotations - Don't rotate all keys simultaneously

Scheduled Rotation

For applications with maintenance windows:

1. Set a key expiration that aligns with your maintenance schedule
2. Rotate the key during your maintenance window
3. Update all applications with the new key
4. Verify functionality before ending maintenance

Environment Variables

Store your API key in environment variables to simplify rotation:

# .env file
APIVERVE_API_KEY=apv_your_new_key_here

# Application code reads from environment
const apiKey = process.env.APIVERVE_API_KEY;

This approach means rotation only requires updating the environment variable, not changing application code.

Forms Key Rotation

If you use VerveKit Embedded Forms, you also have a separate Forms key that can be rotated.

Key Differences

Best Practices

Before Rotating

• Inventory all usage - Know everywhere your API key is used before rotating
• Prepare deployment - Have your deployment process ready to push the new key
• Test in staging - Verify your rotation process works in a non-production environment
• Schedule appropriately - Rotate during low-traffic periods when possible

During Rotation

• Copy immediately - Copy the new key as soon as it's generated
• Deploy quickly - Minimize the time between rotation and deployment
• Monitor for errors - Watch your logs for 401 errors indicating missed updates

After Rotating

• Verify functionality - Test critical API calls to confirm the new key works
• Check all services - Ensure every application using the API has been updated
• Document the rotation - Record when and why the rotation occurred
• Schedule next rotation - If using manual rotation, set a reminder for the next one

Rotation Schedule Recommendations

Emergency Rotation

If you suspect your API key has been compromised, rotate immediately:

1. Rotate now - Don't wait; go to your dashboard and rotate immediately
2. Check usage - Review your analytics for unusual activity
3. Update applications - Push the new key to all your services as quickly as possible
4. Investigate the leak - Determine how the key was exposed to prevent future incidents
5. Audit access - Check if any unauthorized actions were taken during the exposure window

Troubleshooting

401 Errors After Rotation

If you're getting 401 errors after rotating:

• Check the key value - Ensure you copied the complete new key including the apv_ prefix
• Verify deployment - Confirm the new key has been deployed to all services
• Check environment variables - Make sure environment variables have been updated and reloaded
• Clear caches - Some systems cache credentials; restart services if needed
• Check for hardcoded keys - Search your codebase for any hardcoded old key values

Forgot to Copy New Key

If you rotated but didn't copy the new key:

• Go to your API Keys dashboard
• Your current key is always visible (click the eye icon to reveal)
• Copy it and update your applications

Key Expired Unexpectedly

If your key expired and you weren't prepared:

1. Rotate to generate a new key immediately
2. Consider setting a longer expiration or using calendar reminders
3. Set up monitoring to alert you before expiration

For detailed recovery steps and prevention strategies, see Key Expiration Recovery.