API-Keys für MCP- und REST-Clients

API-Keys authentifizieren Clients für das Model Context Protocol (MCP) und die REST-API gegen Ihr Customermates-CRM. Legen Sie einen Key pro Client an, speichern Sie ihn in einer Umgebungsvariable und löschen Sie ihn, wenn das Gerät oder das Teammitglied, das ihn hatte, wegfällt.

API-Key anlegen: Wie lege ich einen API-Key an?

Öffnen Sie in den Einstellungen API-Schlüssel und klicken Sie auf Hinzufügen. Der Dialog API-Key hinzufügen bietet zwei Wege:

Standard-API-Key: Geben Sie unter Name an, wo der Key eingesetzt wird, zum Beispiel Claude Desktop, privater Laptop (bis zu 255 Zeichen), wählen Sie optional unter Läuft ab ein Datum und klicken Sie auf Speichern. Der Key wird einmal unter API-Schlüssel erfolgreich erstellt angezeigt; kopieren Sie ihn, bevor Sie den Dialog schließen.
Schnellverbindungen: Wählen Sie Claude, ChatGPT & Codex, Cursor oder Gemini und dann die Einrichtung, die zu Ihrer Nutzung passt. Bei einer lokalen Einrichtung (Claude Code oder Desktop, dann Claude Code oder Claude Desktop; Codex CLI oder IDE; Cursor oder Gemini) klicken Sie auf API-Key erstellen: Der Dialog legt den Key an und zeigt das Setup-Snippet dieses Clients mit bereits eingesetztem Key. Claude-Konto und ChatGPT-App verbinden sich stattdessen per OAuth und legen keinen Key an. Schließen Sie den Dialog, wenn Sie fertig sind.

Ein Key aus den Schnellverbindungen trägt den Namen seines Clients (Claude Code, Claude Desktop, Codex, Cursor oder Gemini) und läuft 365 Tage nach der Erstellung ab; einen anderen Namen oder ein anderes Datum können Sie dort nicht wählen. Der Dialog zeigt den Ablaufzeitpunkt unter dem Setup-Snippet. Der KI-Schritt des Onboarding-Assistenten legt seine Keys genauso an. Name und Ablaufdatum eines Keys lassen sich nach der Erstellung nicht mehr ändern.

Keys gehören dem Nutzer, der sie angelegt hat, und erben dessen Berechtigungen. Jeder Key gehört außerdem zu dem Workspace, in dem er erstellt wurde, und handelt nur dort, auch Keys aus der Zeit, bevor ein Login zu mehreren Workspaces gehören konnte; siehe Workspaces.

Wer kann API-Keys anlegen und sehen?

Die Seite API-Keys richtet sich nach der Zeile API & Webhooks Ihrer Rolle. Diese Zeile setzt ein Mitglied mit Bearbeiten auf Benutzer & Rollen unter Rollen:

Lesen Alle zeigt API-Keys in den Einstellungen und listet Ihre eigenen Keys. Mit Keine ist der Eintrag ausgeblendet und die Seite lässt sich nicht öffnen.
Erstellen blendet Hinzufügen ein, und Löschen erlaubt das Löschen von Keys. Ohne beide sehen Sie vorhandene Keys, können aber keine anlegen oder löschen.

Eine neue Rolle startet ohne angehakte Checkbox und mit Lesen Keine; ohne Anpassung können also nur Mitglieder mit der eingebauten Rolle Admin API-Keys anlegen. Dieselbe Zeile öffnet auch Webhooks und deren Zustellungen. Wer sie für API-Keys vergibt, lässt das Mitglied also auch jeden Webhook des Workspace sehen und mit Erstellen, Bearbeiten oder Löschen ändern.

Jede Person sieht nur ihre eigenen Keys, und nur die des aktuellen Workspace; um einen Key eines anderen Workspace zu sehen oder zu löschen, wechseln Sie in diesen Workspace. Niemand, auch nicht die Rolle Admin, kann die Keys eines anderen Mitglieds auflisten oder löschen. Kein Assistenten- oder MCP-Tool legt API-Keys an, listet oder löscht sie; verwaltet werden sie nur auf der Seite API-Keys, und der gehostete Assistent kann Ihnen höchstens diese Seite öffnen.

Der Custom Connector für Claude und ChatGPT meldet sich per OAuth an und braucht keinen API-Key. Wie jede MCP-Verbindung braucht er Lesen Alle auf API & Webhooks (MCP-Endpoint). Siehe Mit einem Custom Connector verbinden.

Welche Berechtigung braucht jede Aktion mit API-Keys?

Jede Verwaltung von Keys prüft die Zeile API & Webhooks Ihrer Rolle: Einen Key anzulegen braucht Erstellen, ihn zu ändern Bearbeiten, ihn zu löschen Löschen, und Ihre Keys zu lesen oder aufzulisten Lesen Alle. Ein Mitglied mit Status Inaktiv kann keine Keys verwalten. Keys verwalten Sie nur auf der Seite API-Keys; die zugrunde liegenden Endpunkte unter /api/auth/api-key/ beantworten direkte Anfragen mit 404, sodass jeder Key zu dem Workspace gehört, in dem er angelegt wurde. Diese Prüfungen gelten nur für die Verwaltung von Keys; was ein Aufruf mit einem Key darf, richtet sich nach der Rolle seines Eigentümers, siehe Welche Berechtigungen hat ein Key.

Wie kann ich einen Key nutzen, und in welchen Header gehört er?

Senden Sie ihn bei jeder Anfrage im Header x-api-key, hier an den MCP-Endpunkt <BASE_URL>/api/v1/mcp, wobei <BASE_URL> die Adresse ist, unter der Sie Customermates öffnen:

curl -H "x-api-key: $CUSTOMERMATES_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     <BASE_URL>/api/v1/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Der Header Accept: application/json, text/event-stream wird vom MCP-Streamable-HTTP-Transport verlangt; ohne ihn liefert der Endpoint 406 Not Acceptable. Bei MCP-Clients gehört der Key in die Konfiguration des Clients, siehe CLI- und Editor-Clients und ChatGPT mit einem API-Key.

Die REST-API nimmt denselben Header. Dieser Aufruf listet die Datensatztypen, auf die Sie zugreifen können:

curl -H "x-api-key: $CUSTOMERMATES_API_KEY" \
     -H "Content-Type: application/json" \
     <BASE_URL>/api/v1/model/discover \
     -d '{}'

Alle REST-Operationen mit Request und Response stehen in der API-Referenz.

Was liefert ein abgelehnter REST-Aufruf?

Jeder REST-Endpunkt beantwortet einen abgelehnten Aufruf mit demselben JSON-Body: einem error-Objekt mit kind und den issues, die MCP in _meta.failure liefert (siehe Wenn ein Aufruf abgelehnt wird).

{
  "error": {
    "kind": "not_found",
    "issues": [{ "code": "custom", "path": [], "message": "Webhook ID not found or not accessible.", "customCode": "webhookNotFound" }]
  }
}

Der HTTP-Status folgt error.kind: validation 400, authentication 401, authorization 403, not_found 404, conflict 409, unavailable 422 und rate_limit 429. Jedes Issue nennt den Feld-path, zu dem es gehört, und, wo vorhanden, einen stabilen customCode. error.retryable ist true, wenn ein Nachrichtenanbieter einen Aufruf abgelehnt hat, der später unverändert gelingen kann; auch ein 429 ohne dieses Feld lässt sich wiederholen, siehe den nächsten Abschnitt. Werten Sie kind und customCode aus statt message, die Text für Menschen ist. Ein unerwarteter Serverfehler antwortet mit 500 ohne diesen Body.

Was tut ein Client, wenn ein Aufruf 429 liefert?

rate_limit (HTTP 429) bedeutet, dass der Aufruf gerade nicht laufen konnte und später unverändert gelingen kann. Ein Nachrichtenkanal am Limit seines Anbieters antwortet mit customCode unipileRateLimit und nennt, wann Sie es erneut versuchen können (Nachrichten-Ratenlimits). Ist Customermates selbst überlastet, etwa wenn eine Datenbanktransaktion oder der Verbindungspool in ein Zeitlimit läuft oder ein Schreibzugriff länger als einige Sekunden auf eine andere Änderung im Workspace wartet, zum Beispiel einen großen Import, antwortet der Aufruf mit 429 ohne customCode und mit der Meldung The service is busy. Retry the request shortly.. MCP-Tools liefern dieselbe Art rate_limit in _meta.failure, und die App meldet, dass der Workspace beschäftigt ist, damit Sie es erneut versuchen können.

Eine REST-Antwort 429 trägt einen Retry-After-Header mit den zu wartenden Sekunden: Beachten Sie ihn zuerst und wiederholen Sie nicht früher. Ohne ihn wiederholen Sie nach einer Pause, die mit jedem Versuch wächst, etwa 1, 2, 4 und 8 Sekunden plus etwas zufälligem Jitter, und geben Sie nach wenigen Versuchen auf. Wiederholen Sie nicht in einer engen Schleife und senden Sie nicht mehr Aufrufe parallel, das hält den Dienst ausgelastet. Senden Sie eine Schreiboperation mit demselben idempotencyKey erneut, damit eine Änderung, die durchgegangen ist, nicht doppelt angewendet wird.

Wie lange ist ein Key gültig, und laufen Keys ab?

Ein Standard-API-Key läuft nur ab, wenn Sie unter Läuft ab ein Datum wählen; die Voreinstellung Läuft nie ab hält ihn gültig, bis Sie ihn löschen. Ein Datum muss zwischen 1 und 365 Tagen in der Zukunft liegen. Ein Key aus den Schnellverbindungen (Schnellverbindungs-Schlüssel), auch aus dem Onboarding-Assistenten, gilt 365 Tage: Er läuft immer 365 Tage nach der Erstellung ab. Das Ablaufdatum lässt sich nicht verlängern: Legen Sie vorher einen neuen Key an und aktualisieren Sie den Client. Jede Key-Karte zeigt Erstellt am, Läuft ab (Nie, wenn kein Datum gesetzt ist) und Zuletzt verwendet.

Wie kann ich einen Key widerrufen, löschen oder rotieren?

Klicken Sie unter API-Schlüssel auf die Karte des Keys und wählen Sie Löschen; nach der Bestätigung ist er sofort ungültig. Zum Löschen brauchen Sie Löschen auf API & Webhooks. Eine eigene Rotate- oder Revoke-Aktion fehlt: Zum Rotieren legen Sie einen neuen Key an, stellen jeden Client darauf um und löschen den alten.

Rotieren Sie, wenn ein Gerät mit dem Key verloren oder kompromittiert ist, ein Teammitglied mit Zugriff geht oder Sie einen Leak vermuten. Mit einem Key pro Client löschen Sie einen Client, ohne die anderen zu brechen; im Audit-Log steht aber der Nutzer, nicht der Key. Speichern Sie Keys in einer Umgebungsvariable oder einem Passwort-Manager, nie in einer committeten Datei.

Nur der Besitzer kann einen Key löschen. Um die Keys eines ausscheidenden Mitglieds zu stoppen, setzen Sie unter Mitglieder seinen Status auf Inaktiv und klicken auf Speichern. Dafür brauchen Sie Bearbeiten und Leserecht Alle auf Benutzer & Rollen. Danach wird jeder Aufruf mit seinen Keys abgelehnt, der Daten liest oder ändert. Auch der Entzug von Lesen Alle auf API & Webhooks stoppt seine Keys für MCP und REST, siehe Welche Berechtigungen hat ein Key. Aus Workspace entfernen unter Mitglieder widerruft die Keys und MCP-Verbindungen des Mitglieds für diesen Workspace ebenfalls sofort (Wie genehmige, bearbeite, deaktiviere oder entferne ich ein Mitglied?), und verlässt ein Mitglied einen Workspace selbst, verliert es seine Keys für diesen Workspace sofort (einen Workspace verlassen).

Welches Format hat ein Key, und wie lang darf sein Name sein?

Der Name eines Keys ist 1 bis 255 Zeichen lang. Keys bestehen aus 64 ASCII-Buchstaben (a-z A-Z), erzeugt vom better-auth-API-Key-Plugin und gehasht gespeichert. Der vollständige Key wird nur bei der Erstellung angezeigt und lässt sich danach nicht mehr abrufen.

Welche Berechtigungen hat ein Key, und kann ich ihn auf Lesezugriff beschränken?

Alles, was sein Besitzer im Workspace des Keys darf, und nicht mehr. Ein Berechtigungs-Scoping pro Key gibt es nicht, ein Key lässt sich also nicht auf Lesezugriff beschränken. Jeder Aufruf wird gegen die aktuelle Rolle des Besitzers geprüft. Eine Änderung dieser Rolle, etwa wenn das Mitglied von der Rolle Admin in eine eigene Rolle mit weniger Rechten wechselt, gilt für seine Keys also ab dem nächsten Aufruf. Steht der Status des Besitzers auf Inaktiv, wird jeder Aufruf mit seinen Keys abgelehnt, der Workspace-Daten liest oder ändert.

Ein Key funktioniert, wie ein MCP-OAuth-Token, außerdem nur, solange die Rolle seines Besitzers Lesen Alle auf API & Webhooks hat; das wird bei jedem Aufruf geprüft, auch für später erneuerte Tokens. Ohne diese Berechtigung antwortet MCP mit 403 und error: insufficient_permissions, REST mit 403, kind authorization und customCode insufficientPermissions. Die angemeldete Nutzung der Web-App bleibt davon unberührt.

In Customermates Cloud lehnt ein Workspace, der noch auf seinen ersten Tarif wartet, etwa ein zusätzlicher Workspace ohne Testphase, seine Keys und OAuth-Tokens ab: MCP antwortet mit 403 und error: plan_required, REST mit 403, kind authorization und customCode workspacePlanRequired. Auch das Anlegen eines Keys braucht einen nutzbaren Tarif. Sobald ein Admin einen Tarif wählt, funktionieren die vorhandenen Keys wieder. Ein Workspace, dessen Testphase endete oder dessen bezahltes Abonnement ausgelaufen ist, behält seine vorhandenen Keys und Verbindungen, bis seine Mitglieder auf Inaktiv gesetzt werden, siehe Was passiert, wenn die Testphase endet?.

Weiter

Schnellstart: erster End-to-End-Lauf.
MCP-Übersicht: was ein Key freischaltet.