API und MCP

Authentifizierung

Alle API-Aufrufe sprechen mit dem Backend von hermine.ai desk (in den Beispielen https://api.hermine-desk.example.com, lokal http://localhost:4100). Zwei Header brauchen Sie fast immer:

X-Tenant ist die Subdomain Ihres Workspace (z. B. acme): hermine.ai desk trennt Workspaces strikt auf Datenbankebene, der Header wählt Ihren aus. Authorization: Bearer trägt ein JWT aus der signIn-Mutation. Access-Tokens laufen nach 15 Minuten ab, Refresh-Tokens nach 30 Tagen; mit refreshSession tauschen Sie einen gültigen Refresh-Token gegen ein frisches Paar.

curl -s https://api.hermine-desk.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant: acme" \
  -d '{
    "query": "mutation($email: String!, $password: String!) { signIn(input: { email: $email, password: $password }) { accessToken refreshToken user { id email } errors } }",
    "variables": { "email": "simon@example.com", "password": "geheim" }
  }'

GraphQL-Endpunkt

Die gesamte App läuft über POST /graphql (JSON-Body mit query und optional variables). Rechte werden pro Feld geprüft: ohne Anmeldung antwortet die API mit UNAUTHENTICATED, ohne ausreichende Rechte mit NOT_AUTHORIZED. In der Entwicklungsumgebung ist GraphiQL unter /graphiql erreichbar.

Daneben gibt es zwei REST-Nebenrouten mit derselben Auth: POST /uploads nimmt Dateien als Multipart entgegen und liefert eine signedId für Mutationen wie createCrmDocument, und GET /events/desks/:desk_key ist der SSE-Änderungsfeed eines Desks.

curl -s https://api.hermine-desk.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{ "query": "{ currentUser { id email fullName role } }" }'

curl -s https://api.hermine-desk.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "query($deskKey: String!) { conversations(deskKey: $deskKey, limit: 10) { id subject status company { name } } }",
    "variables": { "deskKey": "support" }
  }'

curl -s https://api.hermine-desk.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "query": "mutation($name: String!, $domain: String) { createCompany(input: { name: $name, domain: $domain }) { company { id name } errors } }",
    "variables": { "name": "Nordwind Logistik GmbH", "domain": "nordwind.example" }
  }'

MCP für externe KI-Agenten

hermine.ai desk stellt pro Desk einen MCP-Server bereit (POST /mcp, eine JSON-RPC-Nachricht pro Request). Externe Agenten wie Claude Code oder Cursor bekommen damit genau die Werkzeuge, die der eingebaute Assistent auf diesem Desk hat, nie mehr: die Lese-Tools (knowledge.search, conversations.search, conversations.get, dazu Lookups aktiver Konnektoren) plus die nutzerautorisierten Aktions-Tools (Antworten, Status, Deals, Wiedervorlagen und weitere).

Zusätzlich zu Authorization und X-Tenant wählt der Header X-Desk-Key den Desk; Ihre Desk-Mitgliedschaft wird geprüft und jeder Tool-Aufruf landet als mcp.tool_called-Event im Audit-Log (nur Metadaten, nie Inhalte).

claude mcp add --transport http hermine.ai https://api.hermine-desk.example.com/mcp \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "X-Tenant: acme" \
  --header "X-Desk-Key: support"

{
  "mcpServers": {
    "hermine.ai": {
      "type": "http",
      "url": "https://api.hermine-desk.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>",
        "X-Tenant": "acme",
        "X-Desk-Key": "support"
      }
    }
  }
}

{
  "mcpServers": {
    "hermine.ai": {
      "url": "https://api.hermine-desk.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>",
        "X-Tenant": "acme",
        "X-Desk-Key": "support"
      }
    }
  }
}

Persönliche API-Tokens (PAT)

Für dauerhafte Integrationen und Skripte gibt es persönliche API-Tokens, kurz PAT. Ein PAT ist an Sie als Person gebunden und läuft nicht nach 15 Minuten ab, er löst also genau das Problem der kurzlebigen JWT-Access-Tokens.

Sie legen ihn unter Persönlich, API-Zugang an. Der Token wird genau einmal angezeigt, im Format hermine_pat_…; kopieren Sie ihn sofort und bewahren Sie ihn sicher auf, danach zeigt hermine.ai desk ihn nie wieder. Beim Anlegen wählen Sie die Scopes (Lesen oder Schreiben) und optional ein Ablaufdatum. Einen Token, den Sie nicht mehr brauchen oder der abhandengekommen ist, können Sie jederzeit widerrufen.

Der PAT ersetzt das JWT im Authorization-Header und funktioniert sowohl auf GraphQL als auch auf MCP: Authorization: Bearer hermine_pat_…. Für Agent-Setups und Skripte ist der PAT gegenüber dem kurzlebigen JWT die klar empfohlene Wahl.

curl -s https://api.hermine-desk.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer hermine_pat_xxxxxxxxxxxx" \
  -d '{ "query": "{ currentUser { id email } }" }'

claude mcp add --transport http hermine.ai https://api.hermine-desk.example.com/mcp \
  --header "Authorization: Bearer hermine_pat_xxxxxxxxxxxx" \
  --header "X-Tenant: acme" \
  --header "X-Desk-Key: support"

REST-API v1

Neben GraphQL gibt es eine schlanke REST-API unter /api/v1, gedacht für einfache Integrationen, die keinen GraphQL-Client mitbringen wollen. Sie authentifiziert sich per PAT (Authorization: Bearer hermine_pat_…) plus dem X-Tenant-Header, genau wie GraphQL.

Listen liefern Cursor-Pagination (ein cursor zeigt auf die nächste Seite), und Fehler kommen in einem einheitlichen Fehler-Envelope: { error: { code, message } }. Abgedeckt sind die Kernressourcen conversations, companies, contacts, deals, quotes und projects, jeweils als Liste und Detail plus die wichtigsten Kernverben. Alles Darüberhinausgehende bleibt bewusst GraphQL und MCP vorbehalten, die REST-API deckt die häufigen, einfachen Fälle ab.

curl -s "https://api.hermine-desk.example.com/api/v1/conversations?limit=20" \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer hermine_pat_xxxxxxxxxxxx"

curl -s https://api.hermine-desk.example.com/api/v1/companies/123 \
  -H "X-Tenant: acme" \
  -H "Authorization: Bearer hermine_pat_xxxxxxxxxxxx"

Inbound-E-Mail-Webhook

Eingehende E-Mails (Brevo Inbound Parse oder Postmark Inbound JSON) erreichen hermine.ai desk über eine eigene URL pro E-Mail-Kanal: POST /webhooks/email/:channel_token. Die fertige URL finden Sie in den Kanal-Einstellungen des Desks.

Hier gibt es keinen Login und keinen X-Tenant-Header: der Token in der URL löst den Workspace auf. Authentifiziert wird stattdessen per HMAC-Signatur: der Header X-Webhook-Signature trägt HMAC-SHA256(signing_secret, raw_body) als Hex-Wert; das Signing-Secret hinterlegen Sie am Kanal (es bleibt write-only). Antworten: 200 (angenommen, Verarbeitung asynchron), 401 (Signatur ungültig), 404 (Token unbekannt oder Desk archiviert).

BODY='{"From":"kunde@example.org","Subject":"Hilfe","TextBody":"Hallo"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')
curl -s https://api.hermine-desk.example.com/webhooks/email/$CHANNEL_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIG" \
  -d "$BODY"

Outbound-Webhooks

In die andere Richtung kann hermine.ai desk Ihr System aktiv benachrichtigen: Outbound-Webhooks schicken bei bestimmten Ereignissen eine HTTP-Nachricht an eine URL Ihrer Wahl. So halten Sie ein CRM, ein Data-Warehouse oder eine eigene Automatik auf dem Laufenden, ohne ständig zu pollen.

Sie richten sie unter Einstellungen, Webhooks ein (eine Admin-Aufgabe). Dort tragen Sie Ihre Ziel-URL ein und abonnieren die Events, die Sie interessieren. Jede Auslieferung ist HMAC-SHA256-signiert: Der Header X-Hermine-Signature trägt die Signatur über den rohen Body, sodass Sie auf Ihrer Seite prüfen können, dass die Nachricht wirklich von hermine.ai desk stammt. Das Signing-Secret wird beim Anlegen genau einmal angezeigt. Schlägt eine Zustellung fehl, versucht hermine.ai desk es mit Retry erneut.

const crypto = require("crypto");
const expected = crypto
  .createHmac("sha256", SIGNING_SECRET)
  .update(rawBody)
  .digest("hex");
// vergleichen Sie expected mit dem Header X-Hermine-Signature
const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers["x-hermine-signature"]),
);

Widget einbinden

Das Chat-Widget kommt mit zwei Script-Tags auf jede Website. Den fertigen Schnipsel kopieren Sie aus den Kanal-Einstellungen (Widget-Kanal des Desks); er sieht so aus:

<script>
  window.hermineWidgetSettings = { token: "<WIDGET_TOKEN>", baseUrl: "https://api.hermine-desk.example.com" };
</script>
<script src="https://api.hermine-desk.example.com/widget.js" async></script>