Authentication

Authentication

All FlowCaptain API requests require authentication via a Bearer token in the Authorization header.

API Key Authentication

Authorization: Bearer sk_live_your_api_key

API keys are account-wide — a single key works for every calendar in your account. That's why every request must specify the target calendar via calendarId; the request then operates with that calendar's configuration, availability, and Google Calendar.

Every request also needs your calendar ID — found under Dashboard → Calendar → API → Integration Guide. Pass it as a calendarId field in the JSON body for POST requests, and as a ?calendarId=... query parameter for GET requests and MCP.

Example Request

curl -X POST https://api.flowcaptain.com/api/v1/check-availability \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -d '{"calendarId": "YOUR_CALENDAR_ID", "query": "next Monday"}'

Error Responses

Missing Authorization header:

{
  "error": "Unauthorized — missing Authorization header"
}

HTTP status: 401 Unauthorized

Invalid API key:

{
  "error": "Unauthorized — invalid API key"
}

HTTP status: 401 Unauthorized

Missing calendar ID:

{
  "error": "calendarId is required",
  "code": "MISSING_CALENDAR_ID"
}

HTTP status: 400 Bad Request

Calendar belongs to a different account:

{
  "error": "Calendar does not belong to this account"
}

HTTP status: 403 Forbidden

MCP Authentication

The MCP endpoint (POST /mcp) uses the same Bearer token authentication:

Authorization: Bearer sk_live_your_api_key

The /mcp endpoint additionally requires a calendarId query parameter on the URL — https://api.flowcaptain.com/mcp?calendarId=YOUR_CALENDAR_ID. Without it, the request is rejected.

The Accept header must include application/json, text/event-stream for MCP requests.