FlowCaptainFlowCaptain
Registrieren

API keys

Create, use and revoke API keys — and which errors the API returns when authentication is missing.

Administration › Settings › API Keys

API keys authenticate your voice bot or application with the FlowCaptain API. A key applies to the whole workspace and works for every calendar in it — so every request names the calendar it is about via calendarId.

Create a key

  1. In the sidebar, under Administration, open Settings.
  2. In the API Keys section, click Create API Key.
  3. Under Key Name, enter a name that tells you where the key is used (max. 100 characters, e.g. "Retell production").
  4. Copy the key right away with Copy Key. It won't be shown again.

Expand the API Keys section to see every key of the workspace with its Prefix (e.g. sk_live_xxxx...), Status (Active or Revoked), Last Used and Created. FlowCaptain never shows the full key again after creation.

A key has the format sk_live_ followed by 32 random hex characters.

Use a key

Send the key as a Bearer token in the Authorization header of every request:

Authorization: Bearer sk_live_your_api_key

Add the calendar ID: as a calendarId field in the JSON body for POST requests, as a ?calendarId=... query parameter for GET requests and MCP. You find it pre-filled under Calendar › Name › API, section Integration Guide — which also shows the header with your active key's prefix.

For MCP connections, enter the key in your voice bot platform's authentication settings (see Platform setup).

Manage keys

  • Several keys — Create separate keys for testing and production and for each integration. Then you can revoke one without disturbing the others.
  • Revoke — Click the trash icon in the key's row and confirm with Revoke. This can't be undone; the API rejects the key within a few minutes.
  • Rotate — Create a new key, switch your integration over, then revoke the old one.
  • Keep it secret — A key doesn't belong in public repositories, chat messages or code that runs in the browser. Revoke it immediately if it may have been exposed.

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 ID is not a valid ID

{
  "error": "Invalid calendarId — must be a UUID"
}

HTTP status: 400 Bad Request

Calendar does not belong to the API key's workspace

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

HTTP status: 403 Forbidden

Too many requests

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 42 seconds"
}

HTTP status: 429 Too Many Requests — the limit is 60 requests per minute per workspace. The Retry-After header gives the number of seconds until you can try again.

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.

On the MCP endpoint, the same error cases (missing or invalid key 401, missing calendar ID 400, calendar from another workspace 403, limit exceeded 429) come back as a JSON-RPC error object, for example:

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Missing calendarId query parameter" },
  "id": null
}

See also