Skip to main content
POST
https://nmixhdvexhgizmxlnhqi.supabase.co
/
functions
/
v1
/
regenerate-api-key
Regenerate API Key
curl --request POST \
  --url https://nmixhdvexhgizmxlnhqi.supabase.co/functions/v1/regenerate-api-key \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "key_id": "<string>",
  "grace_period_days": 123,
  "revoke_immediately": true,
  "1-7 days (Default: 7)": {},
  "1-30 days (Extended)": {},
  "Immediate revocation": {}
}
'
{
  "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
  }
}

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

key_id
string
required
The unique identifier of the API key to regenerate
grace_period_days
integer
Number of days the old key remains valid (1-30 days, default: 7)
revoke_immediately
boolean
If true, the old key is revoked immediately without a grace period (default: false)

Response

success
boolean
Indicates if the key was successfully regenerated
new_key
string
The new API key value. This is only returned once and cannot be retrieved again.
key_info
object
Updated key information
migration_info
object
Information about the key transition period

Example 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

1-7 days (Default: 7)
Recommended
Sufficient time for most deployment cycles while maintaining security
1-30 days (Extended)
Available
For complex deployments or when coordinating across multiple teams
Immediate revocation
Emergency
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

  1. Regenerate key with appropriate grace period
  2. Update staging environment with new key
  3. Test thoroughly in staging
  4. Deploy to production before grace period expires
  5. Monitor for errors using old key
  6. 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

400
Bad Request
Invalid request parameters or grace period out of range
401
Unauthorized
Invalid or missing API key
403
Forbidden
Insufficient permissions to regenerate this API key
404
Not Found
API key not found or not accessible
409
Conflict
Key is already in transition period - wait for current transition to complete
429
Rate Limited
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.