# API-Keys, Scopes und Berechtigungen

> Verstehe, wie ein SynCore-API-Key einem Mandanten und einem Benutzer mit begrenzten Rechten zugeordnet ist.

Quelle: https://support.unitedsynergy.com/api/api-keys/

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

| Stufe | Prüfung |
| --- | --- |
| API-Key | Der Schlüssel muss gültig, nicht gesperrt und mit dem Scope `app-tools` ausgestattet sein. |
| Actor-User | Dessen Rollen, aktivierte Apps, Datenrechte und Datenscopes entscheiden, welche Tools sichtbar und ausführbar sind. |

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](https://support.unitedsynergy.com/benutzer/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](#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.

> **Rohwert sofort sichern**
>
> Verlierst du den einmal angezeigten Rohwert, kann SynCore ihn nicht wiederherstellen. Dann wird der alte Schlüssel gesperrt und ein neuer ausgegeben.

## 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](https://support.unitedsynergy.com/mcp/verbinden/), 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](https://support.unitedsynergy.com/api/spezialanbindungen/). 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.

> **Kein automatischer Ablauf**
>
> Ein API-Key läuft nicht von selbst ab. So fällt keine Integration ohne Vorwarnung aus. Tauschen und Sperren passieren immer bewusst.

## 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.

| Einstellung | Wirkung |
| --- | --- |
| Löschen erlaubt | Aus: Tools, die Daten löschen, fehlen im Katalog und in der Tool-Liste deines MCP-Clients. Ein Aufruf trotzdem endet mit `403`. Neue Schlüssel bekommen „aus“, Schlüssel von vor dem 31.10.2026 behalten das Löschen. |
| Grenze je Stunde | Höchstzahl Löschungen über diesen Schlüssel in einer Stunde, Standard 200. Die nächste Löschung endet mit `429`, danach ist Löschen über den Schlüssel gesperrt und die Plattformadministration bekommt einen Alarm. Lesen, Anlegen und Ändern laufen weiter. |

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

| Was | Wo abgelegt | Wer nutzt es |
| --- | --- | --- |
| Dein SynCore-API-Key im Klartext | Auf der Seite der Integration: Secret Store oder geschützte Umgebungsvariable | Nur die Integration |
| Derselbe Schlüssel in SynCore | Nur als SHA-256-Hash mit Präfix, nicht umkehrbar | SynCore prüft damit jede Anfrage |
| Zugangsdaten, die SynCore für andere Dienste braucht, zum Beispiel Kartendienst, Mailversand oder angebundene externe Tools | Im **Credential Store** der Admin-Konsole, je Mandant verschlüsselt (AES-256-GCM) | Nur SynCore selbst. Anlegen, Ändern und Löschen stehen im Audit-Log, der letzte Zugriff wird vermerkt |

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

```http
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

| Status | Bedeutung |
| --- | --- |
| `401` | Schlüssel fehlt, ist unbekannt oder wurde gesperrt. |
| `403` | Scope `app-tools` fehlt, kein Actor-User ist zugeordnet, dessen Berechtigung reicht nicht aus, oder der Schlüssel darf nicht löschen bzw. ist für Löschungen gesperrt. |
| `429` | Zu viele Anfragen mit diesem Schlüssel (warte die Sekunden aus `Retry-After` ab) oder die Grenze für Löschungen je Stunde ist erreicht (dann bleibt Löschen gesperrt, bis die Plattformadministration freigibt). |

Mehr Fälle mit den genauen Meldungen stehen unter [Wenn eine API-Anfrage scheitert](https://support.unitedsynergy.com/api/fehlerbehebung/).

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