Overview
Regenerate an API key to get a new key value while keeping all existing configuration, permissions, and metadata. This is useful when a key may have been compromised or when following security best practices for key rotation.
The old key value will be invalidated after a grace period (default 7 days). Update your applications with the new key before the grace period expires.
Authentication
This endpoint requires authentication using a secret API key with appropriate team permissions.
curl -X POST "https://nmixhdvexhgizmxlnhqi.supabase.co/functions/v1/regenerate-api-key" \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"key_id": "01HN2X4Y8Z9ABCDEF123456789",
"grace_period_days": 7
}'
Request Body
The unique identifier of the API key to regenerate
Number of days the old key remains valid (1-30 days, default: 7)
If true, the old key is revoked immediately without a grace period (default: false)
Response
Indicates if the key was successfully regenerated
The new API key value. This is only returned once and cannot be retrieved again.
Updated key information Unique identifier for the API key
Display name of the API key
Type of key: pk (public) or sk (secret)
Environment: test or live
Key prefix (e.g., pk_test_, sk_live_)
Last 4 characters of the new key (for identification)
ISO 8601 timestamp when the grace period ends and old key is revoked
ISO 8601 timestamp when the key was regenerated
Information about the key transition period Show Migration Info Properties
When the old key will stop working
Number of days both keys will work
Whether both old and new keys currently work
Example Response
Success Response
Error Response
{
"success" : true ,
"new_key" : "pk_test_01HN2X5Z9A0BCDEFG123456789_AbCdEfGhIj" ,
"key_info" : {
"id" : "01HN2X4Y8Z9ABCDEF123456789" ,
"name" : "Production Frontend Key" ,
"key_type" : "pk" ,
"environment" : "test" ,
"key_prefix" : "pk_test_" ,
"last_four" : "6789" ,
"transition_ends_at" : "2024-01-22T14:30:00Z" ,
"regenerated_at" : "2024-01-15T14:30:00Z"
},
"migration_info" : {
"old_key_expires_at" : "2024-01-22T14:30:00Z" ,
"grace_period_days" : 7 ,
"both_keys_valid" : true
}
}
Grace Period Management
During Grace Period
Both keys work : Old and new keys are both valid
Dashboard indication : Shows “Transition Active” status
Usage tracking : Both keys count toward your usage limits
Audit logging : Tracks usage of both key versions
Grace Period Options
Sufficient time for most deployment cycles while maintaining security
For complex deployments or when coordinating across multiple teams
Old key stops working immediately - use only for compromised keys
Best Practices
Key Rotation Schedule
// Example: Automated quarterly key rotation
const rotateApiKeys = async () => {
const keys = await getActiveApiKeys ();
for ( const key of keys ) {
const ageInDays = ( Date . now () - new Date ( key . created_at )) / ( 1000 * 60 * 60 * 24 );
if ( ageInDays > 90 ) { // Rotate every 90 days
console . log ( `Rotating key: ${ key . name } ` );
const response = await regenerateKey ( key . id , { grace_period_days: 14 });
if ( response . success ) {
// Update configuration management system
await updateKeyInConfigSystem ( key . name , response . new_key );
// Schedule reminder to verify deployment
scheduleVerificationReminder ( key . name , response . migration_info . old_key_expires_at );
}
}
}
};
Deployment Strategy
Regenerate key with appropriate grace period
Update staging environment with new key
Test thoroughly in staging
Deploy to production before grace period expires
Monitor for errors using old key
Verify new key usage in dashboard analytics
Emergency Rotation
For compromised keys:
// Emergency key rotation - immediate revocation
const emergencyRotateKey = async ( keyId ) => {
const response = await regenerateKey ( keyId , {
revoke_immediately: true
});
if ( response . success ) {
// Immediately update all environments
await Promise . all ([
updateProductionKey ( response . new_key ),
updateStagingKey ( response . new_key ),
updateDevelopmentKey ( response . new_key )
]);
// Alert team
await sendSecurityAlert ( `Key ${ keyId } rotated due to compromise` );
}
};
Error Codes
Invalid request parameters or grace period out of range
Invalid or missing API key
Insufficient permissions to regenerate this API key
API key not found or not accessible
Key is already in transition period - wait for current transition to complete
Too many requests, retry after the specified time
Monitoring Regenerated Keys
Dashboard Indicators
Transition Status : Shows countdown to old key expiration
Usage Tracking : Separate metrics for old vs new key usage
Alert Badges : Visual indicators when keys are in transition
API Monitoring
// Check transition status
const checkKeyTransition = async ( keyId ) => {
const response = await fetch ( `/api/keys/ ${ keyId } ` , {
headers: { 'Authorization' : `Bearer ${ secretKey } ` }
});
const keyInfo = await response . json ();
if ( keyInfo . transition_ends_at ) {
const timeRemaining = new Date ( keyInfo . transition_ends_at ) - new Date ();
const daysRemaining = Math . ceil ( timeRemaining / ( 1000 * 60 * 60 * 24 ));
console . log ( `Key transition ends in ${ daysRemaining } days` );
if ( daysRemaining <= 2 ) {
console . warn ( '⚠️ Key transition ending soon - ensure new key is deployed' );
}
}
};
Audit Trail
Every key regeneration creates audit log entries:
Regeneration Event : Who regenerated the key and when
Grace Period : Duration and expiration details
Key Usage : Tracking of both old and new key usage
Expiration Event : When the old key was finally revoked
Remember to save the new key value immediately - it cannot be retrieved again after the initial response. Use secure storage and never log the full key value.