API-Keys

API-Keys authentifizieren Clients für das Model Context Protocol (MCP) und die REST-API gegen Ihr Virtual Marketer 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 & Konnektoren → Hinzufügen. 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: $VM_CRM_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     https://crm.virtual-marketer.de/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

Einen Rotate-Knopf gibt es nicht — Rotieren sind drei Schritte, in dieser Reihenfolge: neuen Key anlegen, alle Clients umstellen, alten Key löschen. So steht kein Client zwischendurch ohne gültigen Key da. Profil → API & Konnektoren → Hinzufügen, danach der alte Key → Löschen.

Widerrufen

Profil → API & Konnektoren, Key anklicken, dann Löschen. Der Key wirkt sofort nicht mehr, und es entsteht kein Ersatz. Nutzen Sie das, wenn ein Key abgeflossen ist oder der Client, der ihn hatte, nicht mehr existiert.

Key-Format

Virtual Marketer CRM-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.