> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syncline.run/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/platform/regenerate-key

> Regenerate your platform API key

## Overview

Generates a new API key for your platform. The old key is immediately invalidated.

<Warning>
  **This action cannot be undone!** Your old API key will stop working immediately. Update all services using the old key before regenerating.
</Warning>

## Authentication

Requires **Platform API Key** in the `X-API-Key` header (the old key you're replacing).

## Request

```bash theme={null}
POST https://api.syncline.run/v1/platform/regenerate-key
```

No request body required.

## Response

```json theme={null}
{
  "success": true,
  "api_key": "sk_live_new_abc123xyz789...",
  "message": "API key regenerated successfully. Save this key - it won't be shown again!"
}
```

<ResponseField name="success" type="boolean">
  Always `true` on successful regeneration
</ResponseField>

<ResponseField name="api_key" type="string">
  Your new API key. **Save this immediately** - it will never be shown again.
</ResponseField>

<ResponseField name="message" type="string">
  Important reminder to save the key
</ResponseField>

## When to Regenerate

### Security Breach

If your API key is exposed (committed to git, leaked in logs, etc.):

```javascript theme={null}
// Immediately regenerate
const response = await fetch('https://api.syncline.run/v1/platform/regenerate-key', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.OLD_SYNCLINE_API_KEY
  }
});

const { api_key } = await response.json();

// Update environment variable immediately
console.log('New API Key:', api_key);
console.log('Update your environment variable NOW');
```

### Regular Rotation

Rotate keys every 90 days as a security best practice:

```javascript theme={null}
// Scheduled key rotation
async function rotateAPIKey() {
  console.log('Rotating Syncline API key...');

  // 1. Generate new key
  const { api_key } = await regenerateKey();

  // 2. Update secrets manager
  await updateSecret('SYNCLINE_API_KEY', api_key);

  // 3. Deploy services with new key
  await deployServices();

  // 4. Verify new key works
  await testNewKey(api_key);

  console.log('✓ API key rotated successfully');
}

// Run every 90 days
schedule.every('90 days').do(rotateAPIKey);
```

### Employee Offboarding

When team members leave who had access to the key:

```javascript theme={null}
async function offboardEmployee(employeeName) {
  console.log(`Offboarding ${employeeName}...`);

  // Regenerate all API keys they had access to
  await regenerateKey();

  // Update documentation
  await notifyTeam(`API keys rotated after ${employeeName} departure`);

  console.log('✓ Keys rotated');
}
```

## Zero-Downtime Rotation

For critical production systems, use this pattern:

```javascript theme={null}
async function rotateKeyWithZeroDowntime() {
  const oldKey = process.env.SYNCLINE_API_KEY;

  // 1. Generate new key
  const { api_key: newKey } = await regenerateKey();

  // 2. Update secrets manager
  await secretsManager.updateSecret('SYNCLINE_API_KEY', newKey);

  // 3. Gradually roll out new key to services
  await rollingDeploy({
    updateEnvVar: { SYNCLINE_API_KEY: newKey },
    strategy: 'blue-green', // Deploy to new instances first
    healthCheck: async () => {
      // Verify new key works
      const response = await fetch('https://api.syncline.run/v1/platform/dashboard', {
        headers: { 'X-API-Key': newKey }
      });
      return response.ok;
    }
  });

  console.log('✓ Zero-downtime rotation complete');
}
```

## Best Practices

### Save Immediately

```javascript theme={null}
const { api_key } = await regenerateKey();

// Bad: Not saving the key
console.log('Key regenerated!');
// ❌ You just lost access to your account!

// Good: Save to secrets manager immediately
await secretsManager.set('SYNCLINE_API_KEY', api_key);
await notifyTeam('New API key saved to secrets manager');
```

### Update All Services

```javascript theme={null}
async function regenerateAndUpdate() {
  const { api_key } = await regenerateKey();

  // Update all services that use the key
  const services = [
    'production-api',
    'staging-api',
    'cron-jobs',
    'background-workers'
  ];

  for (const service of services) {
    await updateServiceSecret(service, 'SYNCLINE_API_KEY', api_key);
  }

  // Verify all services are healthy
  for (const service of services) {
    const healthy = await checkServiceHealth(service);
    if (!healthy) {
      throw new Error(`Service ${service} failed after key rotation!`);
    }
  }

  console.log('✓ All services updated successfully');
}
```

### Test Before Deploying

```javascript theme={null}
async function regenerateWithTesting() {
  // Generate new key
  const { api_key } = await regenerateKey();

  // Test new key works
  try {
    const response = await fetch('https://api.syncline.run/v1/platform/dashboard', {
      headers: { 'X-API-Key': api_key }
    });

    if (!response.ok) {
      throw new Error('New key not working!');
    }

    console.log('✓ New key verified');
  } catch (error) {
    console.error('❌ New key test failed:', error);
    throw error;
  }

  // Deploy only after verification
  await deployNewKey(api_key);
}
```

### Keep Audit Trail

```javascript theme={null}
async function regenerateWithAudit() {
  const { api_key } = await regenerateKey();

  // Log rotation event
  await auditLog.create({
    event: 'api_key_rotated',
    timestamp: new Date(),
    rotated_by: currentUser.email,
    reason: 'Scheduled 90-day rotation',
    old_key_prefix: oldKey.substring(0, 12),
    new_key_prefix: api_key.substring(0, 12)
  });

  // Notify team
  await slack.send({
    channel: '#security',
    message: `🔑 Syncline API key rotated by ${currentUser.email}`
  });

  return api_key;
}
```

## Error Responses

### Invalid API Key

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

### Rate Limit

```json theme={null}
{
  "error": "Too many regeneration attempts",
  "message": "Please wait 1 hour between key regenerations"
}
```

## Security Considerations

<Warning>
  **Never commit API keys to version control!**

  Always use environment variables or secrets managers:

  * AWS Secrets Manager
  * Google Secret Manager
  * HashiCorp Vault
  * Environment variables in deployment platform
</Warning>

### Immediate Invalidation

The old key stops working **immediately** upon regeneration:

```javascript theme={null}
const oldKey = 'sk_live_old_abc123...';

// Regenerate
const { api_key: newKey } = await regenerateKey();

// Old key now INVALID
try {
  await fetch('https://api.syncline.run/v1/platform/dashboard', {
    headers: { 'X-API-Key': oldKey }
  });
} catch (error) {
  console.log('Old key no longer works ✓');
}

// New key works
await fetch('https://api.syncline.run/v1/platform/dashboard', {
  headers: { 'X-API-Key': newKey }
}); // ✓ Success
```

### No Grace Period

Unlike some services, there is **no grace period** where both keys work. Plan your rotation accordingly.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Platform Dashboard" icon="gauge" href="/api-reference/platform-dashboard">
    Verify new key works
  </Card>

  <Card title="Platform Settings" icon="gear" href="/api-reference/platform-settings">
    Configure platform settings
  </Card>
</CardGroup>