API Key Expiration

Why Use Key Expiration?

Automatic key expiration provides several security benefits:

• Enforce rotation schedules - Ensure credentials are rotated on a predictable cadence without relying on manual processes
• Limit credential lifespan - Reduce the window of opportunity for compromised keys to be exploited
• Meet compliance requirements - Many security frameworks (SOC 2, PCI-DSS, ISO 27001, HIPAA) require periodic credential rotation
• Clean up forgotten keys - Automatically invalidate keys that may have been provisioned and forgotten
• Encourage good hygiene - Build credential rotation into your operational processes

Expiration Options

When you rotate your API key, you can choose an expiration period for the new key:

Choosing an Expiration Period

Consider these factors when selecting an expiration period:

• Compliance requirements - Check if your industry or security framework mandates specific rotation intervals
• Operational overhead - Shorter periods mean more frequent rotations and deployments
• Risk tolerance - Shorter periods limit exposure but require more active management
• Deployment complexity - Consider how easy it is to update keys across your systems

Setting Key Expiration

Key expiration is configured during the rotation process:

1. Go to API Keys in your dashboard
2. Click Rotate Key on your primary API key
3. Select your desired expiration period from the dropdown
4. Click Rotate Key to confirm

The new key will be generated with the selected expiration date.

Changing Expiration on an Existing Key

You cannot change the expiration date of an existing key. To change the expiration:

1. Rotate to a new key
2. Select the desired expiration period during rotation
3. Update your applications with the new key

Monitoring Key Expiration

Your dashboard shows the expiration status of your API key with visual indicators:

Expiration Alerts

The dashboard provides visual warnings as your key approaches expiration:

• 14 days before - Yellow "expiring soon" indicator appears
• 7 days before - More prominent warning
• On expiration - Red "Expired" badge, key stops working

What Happens When a Key Expires

When your API key reaches its expiration date:

1. Immediate invalidation - The key stops working at the exact expiration time
2. API requests fail - All requests using the expired key receive a 401 error
3. Dashboard shows expired status - Red "Expired" badge appears
4. Rotation required - You must rotate to a new key to restore access

Error Response

Requests made with an expired key receive this error:

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

Sub-Keys Are Not Affected

Important: Sub-keys do not inherit expiration from the primary key.

• Sub-keys continue working even if the primary key expires
• Sub-keys don't have their own expiration settings
• To revoke sub-key access, delete them individually

Recovering from Expired Keys

If your key has expired:

1. Go to API Keys in your dashboard
2. You'll see the "Expired" indicator on your key
3. Click Rotate Key
4. Select your new expiration period
5. Confirm the rotation
6. Copy the new key and update your applications

Service is restored immediately once the new key is deployed to your applications.

Minimizing Downtime

To minimize or eliminate downtime from key expiration:

• Set calendar reminders - Rotate a few days before expiration
• Use sub-keys - Sub-keys don't expire, providing a backup
• Automate deployments - Have a quick process to push new keys
• Monitor your dashboard - Check expiration status regularly

Compliance Considerations

Key expiration helps meet various compliance requirements:

SOC 2

SOC 2 Trust Services Criteria often require:

• Periodic rotation of authentication credentials
• Documentation of credential lifecycle management
• 90-day rotation is a common benchmark

PCI-DSS

PCI-DSS Requirement 8 addresses credential management:

• Requirement 8.2.4: Change user passwords/passphrases at least once every 90 days
• API keys used in payment processing should follow similar guidelines

ISO 27001

ISO 27001 Annex A.9 covers access control:

• Regular review and update of access credentials
• Documented credential management procedures

HIPAA

HIPAA Security Rule (45 CFR 164.312) requires:

• Unique user identification
• Automatic logoff mechanisms
• Regular credential review and rotation supports compliance

Best Practices

Planning

• Choose based on compliance - If you have regulatory requirements, use the shortest required period
• Document your policy - Write down your chosen expiration period and rotation procedures
• Align with other credentials - Consider matching expiration with other credential rotation schedules

Operations

• Rotate before expiration - Don't wait until the last day; rotate with a buffer
• Test rotation process - Practice your rotation procedure before you need it urgently
• Use environment variables - Store keys in environment variables for easy updates
• Automate where possible - Script your key deployment to reduce manual steps

Monitoring

• Check dashboard weekly - Regular checks catch upcoming expirations
• Set multiple reminders - Calendar alerts at 14 days, 7 days, and 3 days before
• Monitor for 401 errors - Sudden 401 spikes may indicate an expired key

Expiration vs. Never Expire

When to use each approach:

Use Expiration When

• You have compliance requirements mandating rotation
• You want to enforce regular credential hygiene
• You're providing temporary access
• Your deployment process makes rotation easy
• You want automatic invalidation of old credentials

Use "Never" When

• You have a manual rotation schedule you trust
• Rotation is operationally complex
• You're in early development and frequently rotating anyway
• You use sub-keys with scoping for access control instead