API-Keys

API-Keys authentifizieren Clients für das Model Context Protocol (MCP) und die REST-API gegen Ihr Customermates-CRM. Ein Key pro Client (Claude, ChatGPT, Zapier etc.), in einer Umgebungsvariable speichern, rotieren, wenn ein Gerät kompromittiert ist oder ein Teammitglied geht.

Key anlegen

Profil → API Keys → Neuer Key. Geben Sie ihm einen Namen, der den Einsatzort beschreibt (z.B. Claude Desktop privater Laptop). Der 64-Zeichen-Key wird einmal angezeigt. Sofort kopieren.

Key nutzen

Im Header x-api-key bei jeder Request:

curl -H "x-api-key: $CUSTOMERMATES_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     https://customermates.com/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.

Für MCP-Clients gehört der Key in die MCP-Config:

• Claude Desktop
• ChatGPT
• Cursor

Hygiene

• Ein Key pro Client. Hält Audit-Logs lesbar und erlaubt Revoke einzelner Clients, ohne andere zu brechen.
• In Umgebungsvariable speichern, nicht in Config-Dateien. ~/.zshrc, 1Password, Bitwarden CLI oder OS-Keychain.
• Rotieren wenn:
  • Ein Gerät mit dem Key verloren oder kompromittiert ist.
  • Ein Teammitglied mit Zugriff geht.
  • Sie einen Leak vermuten (Git-History, CI-Logs, Screenshots).

Rotieren

Profil → API Keys → Key klicken → Rotate. Neuer Key generiert, alter sofort ungültig. Alle Clients aktualisieren.

Widerrufen

Gleicher Ort → Revoke. Key wird ungültig, kein neuer generiert. Nutzen Sie das, wenn Sie keinen Ersatz brauchen.

Key-Format

Customermates-Keys sind 64 Zeichen, Base62 (a-z A-Z 0-9), erzeugt vom API-Key-Plugin. Der vollständige Key wird nur bei der Erstellung angezeigt und lässt sich danach nicht mehr abrufen.

Rechte

Jeder Key erbt die Rechte seines Users. Wenn ein User von Admin auf Member degradiert wird, verlieren seine Keys Admin-Fähigkeiten beim nächsten Call. Separate per-Key-Rechte gibt es heute nicht.

Weiter

• Quickstart: erster End-to-End-Lauf.
• MCP-Übersicht: was Keys freischalten.