Service-API-Keys vs OAuth: Auth-Architektur fuer agentische Plattformen

Im B2B-SaaS-Stack der letzten zehn Jahre war Authentication ein geloestes Problem. Browser-Session-Cookies fuer den User-Login, OAuth fuer Drittpartei-Integrationen, JWT-Tokens fuer Service-zu-Service. Drei Patterns, klar getrennt, jedes mit seinem Einsatzfeld. Dann kam MCP.

MCP-Server bringen eine neue Klasse von Clients: KI-Agenten, die zur Laufzeit Tools aufrufen, oft aus einem stdio-Kontext heraus, ohne Browser, ohne stabilen User-Login. Das bricht die etablierte Auth-Topologie. Wir haben in den letzten sechs Monaten an mehreren MCP-Servern gearbeitet und sind dabei auf einen wiederkehrenden Befund gestossen: keiner der drei klassischen Auth-Pfade laeuft eins-zu-eins, alle drei brauchen Anpassungen, und die Wahl des Pfads bestimmt mehr ueber die Adoption als die Tool-Qualitaet selbst.

Pfad eins: Clerk Session Cookies (Browser-only)

Clerk-Session-Cookies sind das, was unsere Web-UIs verwenden. Ein User logged sich ein, bekommt einen Cookie, der Cookie wird bei jedem Request mitgeschickt, der Server verifiziert ihn gegen Clerk. Das funktioniert perfekt fuer Browser-Kontexte und ist auch fuer die meisten Web-Frontend-Use-Cases der richtige Pfad.

Sobald aber kein Browser im Spiel ist — beispielsweise wenn Claude Desktop einen stdio-MCP-Server startet — gibt es keinen Cookie, der mitgeschickt werden kann. Es gibt keinen Browser-Redirect, keine Session, keine Cookie-Jar. Der MCP-Server muesste eine separate Browser-Session offen halten, um Cookies zu beziehen, was die Komplexitaet explodieren laesst und sich in einem unbeaufsichtigten Background-Prozess sowieso nicht sauber loesen laesst. Clerk-Session-Cookies sind damit fuer MCP-Server kein Kandidat.

Pfad zwei: JWT-Tokens (kurzlebig, refresh-cycle)

JWT-Tokens sind der erste Versuch, das Cookie-Problem zu umgehen. Statt eines Browser-Cookies bekommt der Client ein signiertes Token, das er im `Authorization`-Header mitschickt. Das funktioniert auch ohne Browser — der Client muss nur das Token irgendwie initial bekommen.

Genau dort liegt das Problem. JWT-Tokens sind per Design kurzlebig (typisch 15 Minuten bis eine Stunde) und brauchen einen Refresh-Cycle. Der Refresh-Cycle braucht entweder einen Browser (OAuth-Standard-Flow) oder einen separaten Refresh-Token-Mechanismus, der wiederum sicher gespeichert werden muss. In einem MCP-Server-Kontext heisst das: der Server muss entweder bei jedem Tool-Call ein neues Token anfordern (Performance-Killer) oder Refresh-Tokens auf der Festplatte halten (Security-Risiko). Beides ist unbefriedigend.

JWT-Tokens sind sinnvoll, wenn die Token-Issuance ueber einen vertrauenswuerdigen Identity-Provider laeuft, der Refresh-Tokens sicher haelt — typisch in einer Server-zu-Server-Kommunikation innerhalb der gleichen Infrastruktur. Fuer den MCP-Server-Use-Case, in dem der Client ein User-Desktop ist, brauchen sie eine Wrapping-Schicht, die das Refresh-Problem kapselt.

Pfad drei: Service-API-Keys (langlebig, single-purpose)

Service-API-Keys sind die pragmatische Antwort. Ein Service-User wird auf der Server-Seite definiert, bekommt einen langlebigen Key zugewiesen (typisch sechs bis zwoelf Monate Gueltigkeit), der Key wird in der MCP-Server-Config als Bearer-Token konfiguriert und bei jedem Tool-Call im `Authorization`-Header mitgeschickt.

Vorteile: kein Refresh-Cycle, kein Browser, keine separate User-Session. Die Tokens sind single-purpose (an einen Service-User gebunden, nicht an einen menschlichen User) und damit explizit nicht fuer Cross-Application-SSO geeignet — was in B2B-Kontexten oft genau das Richtige ist. Nachteile: lange Token-Lifetime erhoeht den Blast-Radius bei Leaks, und es braucht einen UI-Workflow fuer Token-Rotation.

Wir haben diesen Pfad fuer den MMM-Wizard-MCP-Server gewaehlt — und beschreiben hier die konkrete Implementation.

Implementation: proxy.ts mit Header-Injection

Der MMM-Wizard hat eine `proxy.ts` (Next.js 16 Middleware-Aequivalent), die alle eingehenden Requests pruefen. Der Workflow ist:

Schritt 1: `Authorization`-Header extrahieren. Wenn er mit `Bearer ` beginnt, wird das Token isoliert.

Schritt 2: Token gegen die Service-API-Keys-Tabelle in der Postgres-Datenbank verifizieren. Die Tabelle haelt `id`, `service_user_id`, `hashed_token`, `expires_at`, `revoked_at`. Der Verifikations-Check ist ein einfacher Hash-Lookup mit Constant-Time-Compare gegen Timing-Attacks.

Schritt 3: Wenn Token gueltig, wird die `service_user_id` als `x-mmm-service-user`-Header an den Backend-Request injiziert. Die Backend-Routes lesen diesen Header und behandeln den Request, als waere er von dem entsprechenden Service-User gekommen.

Schritt 4: Audit-Log-Eintrag mit Token-ID, Service-User-ID, Tool-Name, Timestamp. Jeder Tool-Call ist nachvollziehbar.

Das Pattern ist bewusst einfach gehalten — kein OAuth-Dance, kein Refresh-Logic, keine externe Identity-Provider-Round-Trip. Der Trade-off ist explizit: laengere Token-Lifetimes gegen einfachere Implementation und schnellere Tool-Calls. Im B2B-Kontext mit kontrollierten Service-Identitaeten ist dieser Trade-off vertretbar.

Sprint-5-Outlook: /admin/api-keys UI mit Rotation

Was bisher fehlt, ist die UI fuer Token-Verwaltung. Im aktuellen Stand werden Tokens manuell ueber ein internes Script erstellt — was fuer die ersten Customer-Implementations funktioniert, aber nicht skaliert. Sprint 5 (geplant fuer Juni 2026) bringt eine `/admin/api-keys`-Seite mit:

- Token-Erstellung mit Service-User-Auswahl und Ablaufdatum-Picker.

- Token-Anzeige genau einmal nach Erstellung (anschliessend nur Hash gespeichert).

- Rotation-Workflow: alter Token bleibt 7 Tage parallel gueltig, anschliessend revoked.

- Audit-Trail per Token mit Tool-Call-Histogramm und letzter Nutzung.

- Notification an den Service-User-Owner bei Rotation und 30 Tage vor Ablauf.

Das ist nicht Rocket-Science, aber es ist die Stufe, ab der das Auth-System produktionsreif wird. Ohne Token-Rotation-UI sind langlebige Tokens ein Liability — mit Rotation-UI sind sie eine pragmatische Loesung fuer ein konkretes Problem.

Wann welcher Pfad — die Entscheidungs-Matrix

Browser-Frontend mit User-Login: Clerk Session Cookies. Punkt. Alles andere ist Over-Engineering.

Server-zu-Server innerhalb der gleichen Infrastruktur, mit Identity-Provider: JWT-Tokens. Das ist der Standard-Pfad fuer Microservice-Kommunikation in modernen Stacks.

MCP-Server, Mobile-App-Backend, CLI-Tools, Cron-Jobs, alle Kontexte ohne Browser-Session: Service-API-Keys mit Rotation-UI. Das ist der Pfad, an den die meisten B2B-Teams kommen, sobald sie KI-Agenten ernsthaft in ihre Stacks integrieren.

Die wichtigste Erkenntnis aus sechs Monaten MCP-Server-Bau: die Auth-Wahl ist die einzelne wichtigste Architektur-Entscheidung fuer einen MCP-Server. Wer die falsche Wahl trifft, blockiert sich entweder die Adoption (OAuth-Browser-Flow im stdio-Kontext) oder baut Komplexitaet auf, die nie wieder reduziert werden kann (JWT-Refresh-Tokens ohne sauberen Refresh-Pfad).

Open-Source Pattern auf GitHub

Das gesamte Auth-Pattern — proxy.ts, Service-API-Keys-Tabelle, Header-Injection-Middleware, Audit-Logging — ist Teil des MMM-Wizard-Repos auf GitHub: github.com/Baldri/mmm-wizard. MIT-lizenziert, copy-paste-fertig fuer eigene MCP-Server-Projekte. Wer Fragen zur Adaption hat, findet uns auf digital-opua.ch.