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

# Authentication

> How to authenticate with the Syncline API

## API Keys

All Syncline API requests require authentication using an API key. Your API key identifies your account and tracks usage.

### Get Your API Key

1. Visit [syncline.run/developer/login](https://syncline.run/developer/login)
2. Authenticate with Google
3. Copy your API key from the developer dashboard

<Warning>
  **Keep your API key secret!** Never commit it to version control or share it publicly. Treat it like a password.
</Warning>

## Making Authenticated Requests

Include your API key in the `Authorization` header using Bearer authentication:

```bash theme={null}
curl -X POST https://api.syncline.run/v1/schedule/auto \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attendees": ["user@example.com"],
    "duration_minutes": 30,
    "title": "Meeting",
    "context": "one_on_one",
    "auto": true
  }'
```

## Environment Variables

Store your API key in an environment variable for security:

<CodeGroup>
  ```bash Bash theme={null}
  export SYNCLINE_API_KEY="your_api_key_here"

  curl -X POST https://api.syncline.run/v1/schedule/auto \
    -H "Authorization: Bearer $SYNCLINE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ ... }'
  ```

  ```javascript Node.js theme={null}
  const SYNCLINE_API_KEY = process.env.SYNCLINE_API_KEY;

  const response = await fetch('https://api.syncline.run/v1/schedule/auto', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SYNCLINE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ ... })
  });
  ```

  ```python Python theme={null}
  import os
  import requests

  SYNCLINE_API_KEY = os.environ['SYNCLINE_API_KEY']

  response = requests.post(
      'https://api.syncline.run/v1/schedule/auto',
      headers={
          'Authorization': f'Bearer {SYNCLINE_API_KEY}',
          'Content-Type': 'application/json'
      },
      json={ ... }
  )
  ```
</CodeGroup>

## Calendar Authentication (OAuth)

Before scheduling meetings, users must connect their Google Calendar:

<Tip>
  **Best Practice: Communicate with your users**

  When users go through the OAuth flow, they'll see Google's consent screen requesting permissions for "Syncline" (our infrastructure). To avoid confusion, briefly explain in your UI that you use Syncline for secure calendar integration before redirecting them. For example: *"We use Syncline to securely connect your calendar and schedule meetings on your behalf."*
</Tip>

### User OAuth Flow

1. Direct users to the OAuth endpoint:
   ```
   https://api.syncline.run/oauth/login?user_id=their_email@example.com
   ```

2. User authenticates with Google and grants calendar permissions

3. User is redirected to your success URL with a confirmation

4. Verify calendar connection:
   ```bash theme={null}
   curl https://api.syncline.run/v1/users/user@example.com/status \
     -H "Authorization: Bearer YOUR_API_KEY"
   ```

### Response

```json theme={null}
{
  "email": "user@example.com",
  "calendar_connected": true,
  "last_sync": "2024-01-15T10:30:00Z",
  "provider": "google"
}
```

## Error Responses

### 401 Unauthorized

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

**Solution**: Check that you're including the `Authorization: Bearer YOUR_API_KEY` header.

### 403 Forbidden

```json theme={null}
{
  "error": "Forbidden",
  "message": "API key does not have access to this resource"
}
```

**Solution**: Verify your API key is active and has the required permissions.

### 429 Rate Limited

```json theme={null}
{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded your monthly meeting limit",
  "limit": 100,
  "used": 100,
  "resets_at": "2024-02-01T00:00:00Z"
}
```

**Solution**: Upgrade your plan or wait until the next billing cycle.

## Rate Limits

Rate limits are based on your pricing tier:

| Tier       | Meetings/Month | Rate Limit       |
| ---------- | -------------- | ---------------- |
| Developer  | 25             | 60 requests/min  |
| Starter    | 250            | 90 requests/min  |
| Pro        | 1,000          | 120 requests/min |
| Scale      | 5,000          | 300 requests/min |
| Enterprise | Unlimited      | Unlimited        |

## Best Practices

<AccordionGroup>
  <Accordion title="Store Keys Securely" icon="lock">
    * Use environment variables, not hardcoded values
    * Never commit API keys to version control
    * Rotate keys if they're exposed
  </Accordion>

  <Accordion title="Handle Errors Gracefully" icon="shield">
    * Implement retry logic for 5xx errors
    * Show user-friendly error messages
    * Log errors for debugging
  </Accordion>

  <Accordion title="Monitor Usage" icon="chart-line">
    * Check your usage dashboard regularly
    * Set up alerts for approaching limits
    * Plan upgrades before hitting limits
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Schedule your first meeting
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/schedule-auto">
    Explore all endpoints
  </Card>
</CardGroup>