API-Schlüssel für Agenten: Lesen, Schreiben, Veröffentlichen – und ein Audit-Log, das du wirklich liest
Shager-API-Schlüssel sicher an KI-Agenten vergeben: was read, write und publish erlauben, Sandbox-Übernahme, Aufbewahrung, Rate Limits, Rotation und Audit-Log.
Gib jedem Agenten den engsten Shager-Schlüssel, der seine Aufgabe abdeckt: read fürs Reporting, write für Entwürfe und publish nur für den Schritt, der Beiträge plant. Bewahre Schlüssel in Umgebungsvariablen oder in der Konfiguration des MCP-Clients auf, niemals in Prompts. Widerrufe und rotiere sie im Agenten-Dashboard und lies dessen Audit-Log, das jeden Aufruf eines Agenten auflistet – mindestens wöchentlich, solange sich ein neuer Agent noch einspielt.
Das ist die Richtlinie. Der Rest dieses Artikels erklärt die Gründe und die Mechanik, denn eine Richtlinie, die niemand versteht, wird beim ersten unbequemen Moment umgangen.
Was darf welche Berechtigung?
Jeder Shager-Schlüssel trägt eine oder mehrere von drei Berechtigungen (Scopes). Jede Operation der API gibt an, welche Berechtigung sie braucht; du siehst das als x-scope an jeder Operation im OpenAPI-Dokument. Die MCP-Tools sind dieselben Operationen, es gelten über MCP also dieselben Regeln.
| Berechtigung | Operationen |
|---|---|
| read | whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics |
| write | create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post |
| publish | schedule_post |
Zwei Punkte in dieser Tabelle verdienen Aufmerksamkeit.
Erstens enthält publish eine einzige Operation, und zwar genau die, mit der Inhalte auf Kundenkonten live gehen. Sie zu isolieren, ist der Sinn der Sache. Ein Agent kann fast die gesamte Arbeit erledigen – Medien hochladen, Texte pro Konto entwerfen, Freigabelinks verschicken –, ohne jemals einen Beitrag auf eine Seite bringen zu können.
Zweitens steht cancel_post unter write. Ein Agent, der Entwürfe schreibt, kann einen geplanten Beitrag zurück in den Entwurf holen. Das ist Absicht: Einen Fehler zu stoppen, sollte leichter sein, als einen zu machen.
Ein Schlüssel ohne die nötige Berechtigung bekommt einen Fehler im Standardformat, { "error": { "code", "message" } }, mit HTTP 403. Agenten sollten diesen Fehler melden, statt nach einem anderen Weg drumherum zu suchen – und deine dauerhaften Anweisungen sollten genau das festhalten.
Woher Schlüssel kommen
Es gibt zwei Wege.
Ein Mensch legt den Schlüssel an, unter app.shager.ai/dashboard/agents, und wählt die Berechtigungen. Das ist der normale Weg für eine Agentur, die einem bestehenden Konto einen Agenten hinzufügt.
Der Agent registriert sich selbst. Ein Agent ohne Konto ruft POST https://app.shager.ai/api/v1/agent/signup mit einem agent_name auf und idealerweise mit einer contact_email für seinen Menschen. Er erhält einen api_key, der nur einmal angezeigt wird, und eine claim_url. Dieser Schlüssel funktioniert sofort in einer Sandbox, die bis zu fünf Workspaces anlegen, Medien hochladen, Entwürfe erstellen und lesen kann. Planen oder veröffentlichen, Verbindungslinks für Kunden erstellen oder Freigabeanfragen verschicken kann sie nicht.
curl -s https://app.shager.ai/api/v1/agent/signup \
-H "Content-Type: application/json" \
-d '{"agent_name":"Northwind content agent (Claude Code)",
"contact_email":"ops@northwind-agency.example",
"purpose":"Draft weekly posts for 3 retail clients"}'
Diese Einschränkungen fallen erst weg, wenn ein Mensch die claim_url öffnet, sich anmeldet und die Organisation übernimmt. In diesem Moment entscheidet der Mensch, ob der Schlüssel des Agenten zusätzlich publish bekommt. Übernimmt niemand, läuft die Sandbox nach sieben Tagen ab. Die vollständige Anleitung steht unter /auth.md, die Schritt-für-Schritt-Erklärung in Self-Signup und Übernahme für Agenten.
Die Designentscheidung dahinter ist einfach: Ein Agent kann selbstständig erkunden und vorbereiten, aber echte Konten verbinden und darauf veröffentlichen läuft immer über einen Menschen.
Wie sollten Agenten Schlüssel aufbewahren und senden?
Shager-Schlüssel sind Bearer-Tokens, die als Authorization: Bearer shgr_live_... gesendet werden. Das entscheidende Merkmal eines Bearer-Tokens ist laut RFC 6750, dass jeder, der ihn besitzt, ihn verwenden kann. Nichts anderes beweist die Identität. Die ganze Aufgabe besteht also darin, ihn nicht preiszugeben.
In der Praxis heißt das:
- Umgebungsvariablen, auf die die Konfiguration verweist. Claude Code unterstützt laut seiner MCP-Dokumentation die Expansion von
${VAR}in den Headern der.mcp.json. Die Datei kann ins Repository; der Schlüssel bleibt in der Umgebung. - Niemals in einem Prompt. Ein in den Chat eingefügter Schlüssel landet in Transkripten und Logs und manchmal in geteilten Unterhaltungen.
- Niemals im Ordner eines Kunden. Wenn du pro Kunde Kontextordner führst, haben Schlüssel darin nichts verloren. Solche Ordner werden geteilt und gezippt.
- Ein Schlüssel pro Agentenrolle. Ein Reporting-Job, ein Entwurfs-Agent und ein Planungsschritt sollten sich keinen Schlüssel teilen. Wenn einer durchsickert, widerrufst du einen.
{
"mcpServers": {
"shager": {
"type": "http",
"url": "https://app.shager.ai/api/mcp",
"headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
}
}
}
Der MCP-Server von Shager akzeptiert diesen API-Schlüssel im Header. Clients, die sich stattdessen per OAuth anmelden, etwa ein benutzerdefinierter Connector in Claude oder ChatGPT, bekommen dieselbe Kontrolle: Ein Mensch bestätigt die Verbindung auf Shagers Zustimmungsseite, Veröffentlichen ist ein eigenes Häkchen, das standardmäßig aus ist, und die Verbindung erscheint im selben Audit-Log. Wie die Einrichtung in ChatGPT geht, zeigt Shager und ChatGPT.
Rotation ohne Ausfall
Schlüssel sollten rotiert werden, wenn eine Person mit Zugriff geht, wenn ein Schlüssel offengelegt worden sein könnte und nach einem Zeitplan, den du auch durchhältst. Diese Reihenfolge vermeidet eine Lücke:
- Leg im Dashboard einen neuen Schlüssel mit denselben Berechtigungen an.
- Aktualisiere die Umgebungsvariable dort, wo der Agent läuft.
- Ruf mit dem neuen Schlüssel
whoamiauf, um zu prüfen, ob er funktioniert und die erwarteten Berechtigungen zeigt. - Widerrufe den alten Schlüssel.
Der Widerruf greift für jeden Aufruf mit diesem Schlüssel, über MCP wie über REST.
Rate Limits gehören zur Sicherheit
Jeder Schlüssel ist auf 120 Anfragen pro Minute begrenzt. Ein gut funktionierender Agent kommt da nie in die Nähe: Ein kompletter Wochenentwurf für einen Kunden sind ein paar Dutzend Aufrufe. Wenn ein Agent doch auf HTTP 429 stößt, steckt meist eine Schleife dahinter – ein Agent, der denselben scheiternden Aufruf wieder und wieder versucht. Deine Anweisungen sollten 429 als Stoppsignal behandeln, nicht als Anlass, schneller neu zu versuchen. Zurücktreten, melden, einen Menschen draufschauen lassen.
Das Audit-Log lesen
Das Agenten-Dashboard zeigt ein Audit-Log mit jedem Aufruf eines Agenten. Nützlich ist es nur, wenn jemand es liest. Darauf solltest du in den ersten Wochen mit einem neuen Agenten achten:
- Aufrufe, mit denen du nicht gerechnet hast. Ein Reporting-Agent, der
create_postaufruft, hat falsche Anweisungen oder einen falschen Schlüssel. - Abdriften zwischen Workspaces. Aufrufe, die einen Kunden betreffen, um den es in der Aufgabe gar nicht ging. Das ist das Frühwarnzeichen für den kundenübergreifenden Fehler, um den es in ein Agent, viele Kunden geht.
- Fehlerhäufungen. Wiederholte 403er bedeuten, dass der Agent immer wieder etwas außerhalb seiner Berechtigung versucht. Korrigiere die Anweisungen, nicht die Berechtigung.
Nach ein paar sauberen Wochen reicht ein kurzer wöchentlicher Blick.
FAQ
Sollte der Agent überhaupt jemals die Berechtigung publish haben?
Das kann er, sobald du seinen Entwürfen vertraust und es einen Prüfschritt gibt, entweder Freigabelinks für Kunden oder eine interne Prüfung. Bewährt hat sich, publish auf einem separaten Schlüssel zu halten, den nur ein kurzer, geskripteter Planungsschritt verwendet – so ist der Agent, der schreibt, nicht derselbe, der ausliefert.
Was passiert mit dem Schlüssel eines Agenten, wenn die Sandbox übernommen wird?
Die Organisation gehört dann dem Menschen, und der Schlüssel funktioniert darin weiter. Der Mensch entscheidet bei der Übernahme, ob dieser Schlüssel auch planen und veröffentlichen darf. Er kann ihn jederzeit im Dashboard widerrufen oder neue anlegen.
Lässt sich ein Schlüssel auf einen einzigen Kunden-Workspace beschränken?
Berechtigungen begrenzen, was ein Schlüssel tun darf, nicht, in welchem Workspace er handelt. Trenne Kunden über Workspaces, Kontext pro Kunde und die Gewohnheit, den Workspace vor jedem Schreibvorgang über den Namen aufzulösen – und nutze separate Schlüssel pro Rolle, damit ein Widerruf gezielt bleibt.
Wie es weitergeht
Wenn du deinen ersten Agenten einrichtest, zeigt der Einstiegspunkt für Agenten beide Wege zu einem Schlüssel. Fang mit einem write-Schlüssel an und füge publish erst hinzu, wenn sich die Entwürfe das verdient haben.
