> ## 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.

# Platform Settings

> Get and update platform configuration

## GET /v1/platform/settings

Get your platform's current configuration settings.

### Authentication

Requires **Platform API Key** in the `X-API-Key` header.

### Request

```bash theme={null}
GET https://api.syncline.run/v1/platform/settings
```

### Response

```json theme={null}
{
  "name": "Your Platform Name",
  "email": "developer@yourplatform.com",
  "redirect_uris": [
    "https://yourplatform.com/oauth/callback",
    "http://localhost:3000/oauth/callback"
  ],
  "webhook_url": "https://yourplatform.com/webhooks/syncline",
  "plan": "growth"
}
```

## PUT /v1/platform/settings

Update your platform settings.

### Authentication

Requires **Platform API Key** in the `X-API-Key` header.

### Request

```bash theme={null}
PUT https://api.syncline.run/v1/platform/settings
```

### Request Body

```json theme={null}
{
  "redirect_uris": [
    "https://yourplatform.com/oauth/callback",
    "https://staging.yourplatform.com/oauth/callback",
    "http://localhost:3000/oauth/callback"
  ],
  "webhook_url": "https://yourplatform.com/webhooks/syncline"
}
```

<ParamField body="redirect_uris" type="array">
  Array of allowed OAuth redirect URIs. Must be HTTPS in production (HTTP allowed for localhost).
</ParamField>

<ParamField body="webhook_url" type="string">
  Webhook endpoint URL. Must be HTTPS.
</ParamField>

### Response

```json theme={null}
{
  "success": true,
  "message": "Settings updated successfully",
  "redirect_uris": [
    "https://yourplatform.com/oauth/callback",
    "https://staging.yourplatform.com/oauth/callback",
    "http://localhost:3000/oauth/callback"
  ],
  "webhook_url": "https://yourplatform.com/webhooks/syncline"
}
```

## Configuration Options

### Redirect URIs

OAuth redirect URIs where users are sent after connecting their calendar.

**Requirements:**

* Must be HTTPS in production
* HTTP allowed only for localhost development
* Maximum 5 redirect URIs per platform

**Example:**

```json theme={null}
{
  "redirect_uris": [
    "https://app.yourplatform.com/oauth/callback",
    "https://staging.yourplatform.com/oauth/callback",
    "http://localhost:3000/oauth/callback"
  ]
}
```

### Webhook URL

URL where Syncline sends webhook events.

**Requirements:**

* Must be HTTPS
* Must return 200 OK within 30 seconds
* Should verify webhook signatures

**Example:**

```json theme={null}
{
  "webhook_url": "https://api.yourplatform.com/webhooks/syncline"
}
```

## Use Cases

### Development Environment Setup

```javascript theme={null}
// Set up localhost redirect for development
await updateSettings({
  redirect_uris: [
    'https://app.yourplatform.com/oauth/callback', // Production
    'http://localhost:3000/oauth/callback'          // Development
  ]
});
```

### Multi-Environment Configuration

```javascript theme={null}
// Different settings per environment
const settings = {
  production: {
    redirect_uris: ['https://app.yourplatform.com/oauth/callback'],
    webhook_url: 'https://api.yourplatform.com/webhooks/syncline'
  },
  staging: {
    redirect_uris: ['https://staging.yourplatform.com/oauth/callback'],
    webhook_url: 'https://staging-api.yourplatform.com/webhooks/syncline'
  },
  development: {
    redirect_uris: ['http://localhost:3000/oauth/callback'],
    webhook_url: 'https://webhook-test.com/your-endpoint'
  }
};

const env = process.env.NODE_ENV;
await updateSettings(settings[env]);
```

### Webhook URL Update

```javascript theme={null}
// Update webhook URL
await updateSettings({
  webhook_url: 'https://new-api.yourplatform.com/webhooks/syncline'
});

// Test the new webhook
await fetch('https://api.syncline.run/v1/platform/webhook/test', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.SYNCLINE_API_KEY
  }
});
```

## Error Responses

### Invalid Redirect URI

```json theme={null}
{
  "error": "Invalid redirect URI",
  "message": "Redirect URIs must use HTTPS in production (HTTP allowed for localhost only)"
}
```

### Invalid Webhook URL

```json theme={null}
{
  "error": "Invalid webhook URL",
  "message": "Webhook URL must use HTTPS"
}
```

### Too Many Redirect URIs

```json theme={null}
{
  "error": "Too many redirect URIs",
  "message": "Maximum 5 redirect URIs allowed per platform"
}
```

## Best Practices

### Use Environment Variables

```javascript theme={null}
// Good: Environment-specific configuration
const config = {
  redirect_uris: [
    process.env.OAUTH_REDIRECT_URI,
    'http://localhost:3000/oauth/callback' // Development fallback
  ],
  webhook_url: process.env.WEBHOOK_URL
};

// Bad: Hardcoded production URLs
const config = {
  redirect_uris: ['https://myapp.com/oauth/callback'],
  webhook_url: 'https://myapp.com/webhooks'
};
```

### Validate Webhook URL Before Updating

```javascript theme={null}
// Test webhook endpoint first
async function updateWebhookSafely(newUrl) {
  // Verify endpoint responds
  try {
    const response = await fetch(newUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ test: true })
    });

    if (!response.ok) {
      throw new Error('Webhook endpoint not responding');
    }
  } catch (error) {
    console.error('Webhook validation failed:', error);
    return;
  }

  // Update if valid
  await updateSettings({ webhook_url: newUrl });

  // Send test webhook
  await sendTestWebhook();
}
```

### Keep Redirect URIs Minimal

```javascript theme={null}
// Good: Only necessary URIs
redirect_uris: [
  'https://app.yourplatform.com/oauth/callback',
  'http://localhost:3000/oauth/callback'
]

// Bad: Too many URIs
redirect_uris: [
  'https://app.yourplatform.com/callback1',
  'https://app.yourplatform.com/callback2',
  'https://app.yourplatform.com/callback3',
  'https://staging.yourplatform.com/callback1',
  'https://staging.yourplatform.com/callback2'
]
```

## Related Endpoints

<CardGroup cols={3}>
  <Card title="Regenerate API Key" icon="key" href="/api-reference/platform-regenerate-key">
    Generate new platform API key
  </Card>

  <Card title="Update Webhook" icon="webhook" href="/webhooks">
    Configure webhook settings
  </Card>

  <Card title="OAuth URL" icon="link" href="/api-reference/platform-oauth-url">
    Generate OAuth URLs
  </Card>
</CardGroup>