API-Keys, Scopes und Berechtigungen

Ein API-Key ist kein Generalschlüssel. Er gehört zu genau einem Mandanten und handelt für App-Tools als ein fest zugeordneter Actor-User.

Zweistufiges Berechtigungsmodell

Ein erfolgreicher Katalogaufruf zeigt daher nicht alle SynCore-Funktionen, sondern nur die für diese technische Identität erlaubten Aktionen.

API-Key beantragen

API-Keys stellt die SynCore-Plattformadministration aus, nicht der Mandant selbst. So bereitest du den Antrag vor:

1. Lege für die Integration einen eigenen technischen Benutzer an, zum Beispiel „Integration Warenwirtschaft”. Wie das geht, steht unter Einen Benutzer anlegen.
2. Gib diesem Benutzer nur die Rollen und Datenbereiche, die die Integration wirklich braucht.
3. Wende dich an den Support und nenne: Mandant, Zweck der Integration, den technischen Benutzer, ob der Schlüssel für Test oder Produktion gedacht ist und ob er Daten löschen soll (siehe Löschen über den Schlüssel).

Der vollständige Rohwert beginnt mit syn_ und wird nur unmittelbar nach der Erstellung angezeigt. SynCore speichert danach nur einen SHA-256-Hash und ein kurzes Präfix.

Ausgabe und Widerruf (Plattformadministration)

1. Öffne in der Admin-Konsole unter Zugriff die Seite API Keys. Die Liste zeigt die Schlüssel des aktiven Mandanten. Einen anderen wählst du links über der Tabelle in der Auswahl Mandant; hinter jedem Namen steht die Zahl seiner Schlüssel. Alle Mandanten zeigt alle Schlüssel nur zum Lesen, ohne Aktionen.
2. Klick oben rechts auf Key erzeugen. Es öffnet sich der Dialog MCP-Zugang (App-Tools-Key) mit dem Namen des Mandanten.
3. Wähle unter Actor-User den technischen Benutzer. Zur Auswahl stehen nur Mitglieder dieses Mandanten.
4. Trag unter Bezeichnung einen sprechenden Namen ein (vorbelegt ist „MCP App-Tools”).
5. Soll die Integration löschen dürfen, schalte Löschen erlaubt ein und prüf die Grenze je Stunde (vorbelegt 200). Ohne diesen Schalter löscht der Schlüssel nichts.
6. Klick auf Key erzeugen und übergib den angezeigten Schlüssel sofort auf einem sicheren Weg. Er ist nur dieses eine Mal sichtbar.

Der Schlüssel bekommt immer den Scope app-tools und gilt für die App-Tools-API und für den MCP-Zugang, dessen Adresse unten im Dialog steht. Schlüssel mit anderen Scopes, etwa für eine Newsletter-Anmeldung von deiner Website, stellt United Synergy aus: Spezialanbindungen neben den App-Tools. In der Liste steht er mit Bezeichnung, Präfix, Mandant, Scopes, der Spalte Löschen, Alter, letzter Nutzung und Status. Über ⋯ in seiner Zeile:

• Bearbeiten öffnet den Dialog Key bearbeiten, ebenso ein Klick auf die Zeile. Dort änderst du die Bezeichnung und bei Schlüsseln mit Benutzer den Code-Mode (mit Programme freigeben: Niemand = Programme schreiben sofort mit den Rechten des Benutzers, sonst gibt die gewählte Person jeden Schreibaufruf frei), Löschen erlaubt und die Grenze je Stunde. Speichern übernimmt alles in einem Schritt. Benutzer, Scopes und Laufzeit lassen sich nicht ändern; dafür stellst du einen neuen Schlüssel aus oder rotierst.
• Löschen freigeben erscheint nur, wenn die Grenze überschritten wurde, und hebt die Sperre auf. Dasselbe geht im Dialog Key bearbeiten über den Hinweis oben.
• Widerrufen sperrt den Schlüssel nach einer Rückfrage sofort, Integrationen mit diesem Schlüssel bekommen danach 401.

Ausgabe, Widerruf, Änderungen aus Key bearbeiten (mit altem und neuem Wert), Sperre und Freigabe stehen im Audit-Log.

Die Seite API-Keys der Admin-Konsole zeigt alle Schlüssel mit Alter, letzter Nutzung und Status. Sie markiert Schlüssel, die nie genutzt wurden, seit 90 Tagen still sind oder älter als 180 Tage sind. Abgeschaltet wird dabei nichts.

Schlüssel tauschen

1. Lass einen neuen Schlüssel für denselben Actor-User ausgeben.
2. Stell die Integration auf den neuen Schlüssel um und prüf sie mit einem lesenden Tool.
3. Lass den alten Schlüssel widerrufen.

Ein Mandant kann mehrere aktive Schlüssel haben, deshalb entsteht beim Wechsel keine Lücke.

Actor-User nach dem Least-Privilege-Prinzip

Verwende für eine Integration einen eigenen technischen Benutzer und gib ihm nur die tatsächlich benötigten Rollen und Datenbereiche. Nutze keinen Plattform-Administrator als Actor-User, nur um Berechtigungsprobleme zu umgehen.

Änderungen an Rollen oder aktivierten Apps wirken beim nächsten API-Aufruf. Auch ein gültiger Schlüssel kann deshalb später einen kleineren Katalog oder 403 Forbidden erhalten.

Soll eine Integration nur lesen, gib dem technischen Benutzer eine Rolle, die nur lesen darf. Der Schlüssel kann dann nichts anlegen, ändern oder löschen.

Löschen über den Schlüssel

Jeder Schlüssel trägt zwei Einstellungen zum Löschen. Sie gelten für alles, was über diesen Schlüssel läuft, also App-Tools-API und MCP. In der Oberfläche von SynCore ändern sie nichts, dort entscheiden weiter die Rollen.

Ob der Actor-User etwas löschen darf, entscheiden weiter seine Rollen. Die Einstellungen am Schlüssel schränken nur ein, sie erlauben nie mehr, als die Rollen erlauben. Eine Sperre nach überschrittener Grenze hebt nur die Plattformadministration auf. Viele Datensätze landen beim Löschen im Papierkorb und lassen sich von dort zurückholen, Einträge in Wertelisten werden dagegen endgültig gelöscht.

Schlüssel sicher verwenden

• Übertrage den Schlüssel ausschließlich über HTTPS im Header X-API-KEY.
• Verwende nie Query-Parameter wie ?apiKey=....
• Halte Schlüssel aus Quellcode, Browser-Frontend, Logs, Tickets und Screenshots heraus.
• Speichere ihn in einem Secret Store oder als geschützte Umgebungsvariable.
• Verwende getrennte Schlüssel für Test und Produktion.
• Sperre einen kompromittierten oder nicht mehr benötigten Schlüssel sofort.
• Stimme eine regelmäßige Rotation mit allen beteiligten Systemen ab.

Wo welcher Schlüssel liegt

Leg deinen SynCore-API-Key nicht im Credential Store ab. Der ist für Zugangsdaten gedacht, mit denen SynCore andere Dienste aufruft, nicht für Schlüssel, mit denen andere SynCore aufrufen.

Authentifizierungsbeispiel

GET /api/app-tools?includeStructure=1 HTTP/1.1
Host: syncore.example.com
X-API-KEY: syn_...
Accept: application/json

Der Headername ist nicht case-sensitiv. In der Dokumentation verwenden wir einheitlich X-API-KEY.

Typische Authentifizierungsfehler

Mehr Fälle mit den genauen Meldungen stehen unter Wenn eine API-Anfrage scheitert.

Gib bei einer Supportanfrage nur das sichtbare Schlüsselpräfix und den Namen des Schlüssels an, niemals den vollständigen Rohwert.