Ein Header, mehr nicht

Alle APIs des Maklerportals werden über einen API-Schlüssel authentifiziert. Er geht bei jedem Aufruf im Header apikey mit:

curl https://api.maklerportal.example/v1/objekte \
  -H "apikey: $MAKLERPORTAL_API_KEY"

Es gibt keinen Token-Endpunkt, keine Ablaufzeit und keinen Refresh. Das hält die Anbindung einfach – verlangt aber, dass der Schlüssel wie ein Passwort behandelt wird.

Anwendungen und Schlüssel

Jede Integration ist eine eigene Anwendung. Zu jeder Anwendung gehören ein oder mehrere Schlüssel.

Legen Sie mindestens zwei Anwendungen an: eine für die Sandbox, eine für die Produktion. Wer beides in einer Anwendung führt, kann bei einem Leck nicht mehr gezielt sperren.

Der Schlüssel wird bei der Erzeugung genau einmal angezeigt. Danach lässt er sich nicht mehr auslesen, nur ersetzen. Bewahren Sie ihn in einem Secret-Store auf – nicht in der Versionsverwaltung, nicht in einem Ticket, nicht in einer Konfigurationsdatei im Image.

Scopes

Am Schlüssel hängt, was er darf. Vergeben Sie nur, was der jeweilige Prozess braucht: Ein nächtlicher Import kommt ohne Leserechte auf Provisionen aus.

Fehlt ein Scope, antwortet die API mit 403:

{
  "code": "scope_fehlt",
  "nachricht": "Dem API-Schlüssel fehlt ein erforderlicher Scope.",
  "details": [
    { "feld": "exposes:schreiben", "grund": "nicht_erteilt" }
  ]
}

Schlüssel wechseln

Ein Wechsel ohne Ausfall funktioniert überlappend – deshalb erlaubt eine Anwendung mehrere aktive Schlüssel:

1. Zweiten Schlüssel zur bestehenden Anwendung erzeugen. Beide sind ab sofort gültig.
2. Deployment auf den neuen Schlüssel umstellen.
3. Prüfen, dass keine Aufrufe mehr mit dem alten eintreffen – die Anwendungsübersicht zeigt zuletzt_genutzt_am je Schlüssel.
4. Alten Schlüssel zurückziehen.

Wechseln Sie planmäßig alle 90 Tage und sofort, wenn ein Schlüssel in ein Log, ein Ticket oder ein Repository geraten ist. Ein zurückgezogener Schlüssel wirkt binnen weniger Sekunden.

Was Sie nicht tun sollten

• Den Schlüssel im Browser verwenden. Alles, was auf einem Endgerät läuft, gibt ihn preis. Rufen Sie die APIs serverseitig auf.
• Einen Schlüssel für alles. Ein Schlüssel je Anwendung und Umgebung ist der Unterschied zwischen „einen Zugang sperren" und „alles steht".
• Den Schlüssel in die URL schreiben. Er gehört in den Header; Query-Parameter landen in Server-Logs und im Browserverlauf.