FlowCaptainFlowCaptain
Registrieren

API-Schlüssel

API-Schlüssel erstellen, verwenden und widerrufen — und welche Fehler die API bei fehlender Anmeldung zurückgibt.

Verwaltung › Einstellungen › API-Schlüssel

API-Schlüssel melden deinen Voice Bot oder deine Anwendung bei der FlowCaptain-API an. Ein Schlüssel gilt für den ganzen Workspace und funktioniert für jeden Kalender darin — deshalb nennt jede Anfrage über calendarId, welchen Kalender sie betrifft.

Schlüssel erstellen

  1. Öffne in der Seitenleiste unter Verwaltung die Einstellungen.
  2. Klicke im Abschnitt API-Schlüssel auf API-Schlüssel erstellen.
  3. Vergib unter Schlüsselname einen Namen, an dem du den Einsatzort erkennst (max. 100 Zeichen, z.B. „Retell Produktion“).
  4. Kopiere den Schlüssel sofort mit Schlüssel kopieren. Er wird nicht erneut angezeigt.

Klappst du den Abschnitt API-Schlüssel auf, siehst du alle Schlüssel des Workspaces mit Präfix (z.B. sk_live_xxxx...), Status (Aktiv oder Widerrufen), Zuletzt verwendet und Erstellt. Den vollständigen Schlüssel zeigt FlowCaptain nach dem Erstellen nie wieder.

Ein Schlüssel hat das Format sk_live_ gefolgt von 32 zufälligen Hex-Zeichen.

Schlüssel verwenden

Schick den Schlüssel als Bearer-Token im Authorization-Header jeder Anfrage mit:

Authorization: Bearer sk_live_dein_api_schluessel

Dazu kommt die Kalender-ID: bei POST-Anfragen als Feld calendarId im JSON-Body, bei GET-Anfragen und MCP als Query-Parameter ?calendarId=.... Du findest sie vorausgefüllt unter Kalender › Name › API im Abschnitt Integrations-Anleitung — dort steht auch der Header mit dem Präfix deines aktiven Schlüssels.

Bei MCP-Verbindungen trägst du den Schlüssel in der Authentifizierung deiner Voice-Bot-Plattform ein (siehe Plattform-Einrichtung).

Schlüssel verwalten

  • Mehrere Schlüssel — Lege getrennte Schlüssel für Test und Produktion und für jede Integration an. So kannst du einen widerrufen, ohne die anderen zu stören.
  • Widerrufen — Klicke in der Zeile des Schlüssels auf das Papierkorb-Symbol und bestätige mit Widerrufen. Das lässt sich nicht rückgängig machen; die API lehnt den Schlüssel innerhalb weniger Minuten ab.
  • Wechseln — Erstelle einen neuen Schlüssel, stelle deine Integration um, dann widerrufe den alten.
  • Geheim halten — Ein Schlüssel gehört nicht in öffentliche Repositories, Chat-Nachrichten oder Code, der im Browser läuft. Widerrufe ihn sofort, wenn er sichtbar geworden sein könnte.

Anfrage-Beispiel

curl -X POST https://api.flowcaptain.com/api/v1/check-availability \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_dein_api_schluessel" \
  -d '{"calendarId": "YOUR_CALENDAR_ID", "query": "nächsten Montag"}'

Fehlerantworten

Fehlender Authorization-Header

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

HTTP-Status: 401 Unauthorized

Ungültiger API-Schlüssel

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

HTTP-Status: 401 Unauthorized

Fehlende Kalender-ID

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

HTTP-Status: 400 Bad Request

Kalender-ID ist keine gültige ID

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

HTTP-Status: 400 Bad Request

Kalender gehört nicht zum Workspace des API-Schlüssels

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

HTTP-Status: 403 Forbidden

Zu viele Anfragen

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

HTTP-Status: 429 Too Many Requests — das Limit liegt bei 60 Anfragen pro Minute pro Workspace. Der Header Retry-After nennt die Sekunden bis zum nächsten Versuch.

MCP-Authentifizierung

Der MCP-Endpunkt (POST /mcp) verwendet dieselbe Bearer-Token-Authentifizierung:

Authorization: Bearer sk_live_dein_api_schluessel

Der /mcp-Endpunkt benötigt zusätzlich einen calendarId-Query-Parameter an der URL — https://api.flowcaptain.com/mcp?calendarId=YOUR_CALENDAR_ID. Ohne ihn wird die Anfrage abgelehnt.

Der Accept-Header muss application/json, text/event-stream für MCP-Anfragen enthalten.

Beim MCP-Endpunkt kommen dieselben Fehlerfälle (fehlender oder ungültiger Schlüssel 401, fehlende Kalender-ID 400, fremder Kalender 403, Limit überschritten 429) als JSON-RPC-Fehlerobjekt zurück, zum Beispiel:

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

Siehe auch