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
2. Authenticate with Google
3. Copy your API key from the developer dashboard

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

Making Authenticated Requests

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

curl -X POST https://api.syncline.run/v1/schedule/auto \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attendees": ["[e-mail]"],
    "duration_minutes": 30,
    "title": "Meeting",
    "context": "one_on_one",
    "auto": true
  }'

Environment Variables

Store your API key in an environment variable for security:

Bash

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 '{ ... }'

Calendar Authentication (OAuth)

Before scheduling meetings, users must connect their Google Calendar:

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

User OAuth Flow

1. Direct users to the OAuth endpoint:

   https://api.syncline.run/oauth/login?user_id=[e-mail]
   

2. User authenticates with Google and grants calendar permissions

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

4. Verify calendar connection:

   curl https://api.syncline.run/v1/users/[e-mail]/status \
     -H "Authorization: Bearer YOUR_API_KEY"
   

Response

{
  "email": "[e-mail]",
  "calendar_connected": true,
  "last_sync": "2024-01-15T10:30:00Z",
  "provider": "google"
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Solution: Check that you’re including the Authorization: Bearer YOUR_API_KEY header.

403 Forbidden

{
  "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

{
  "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

Store Keys Securely

• Use environment variables, not hardcoded values
• Never commit API keys to version control
• Rotate keys if they’re exposed

Handle Errors Gracefully

• Implement retry logic for 5xx errors
• Show user-friendly error messages
• Log errors for debugging

Monitor Usage

• Check your usage dashboard regularly
• Set up alerts for approaching limits
• Plan upgrades before hitting limits

Next Steps

Quickstart

Schedule your first meeting

API Reference

Explore all endpoints