---
title: "Authentifizierung"
description: "API-Schlüssel, Scopes und Schlüsselwechsel für Maklerportal-Anwendungen."
url: "https://maklerportal.apim.eu/leitfaeden/authentifizierung"
image: "https://maklerportal.apim.eu/_og/d/c_Ocean.takumi,title_Authentifizierung,description_~QVBJLVNjaGzDvHNzZWwsIFNjb3BlcyB1bmQgU2NobMO8c3NlbHdlY2hzZWwgZsO8ciBNYWtsZXJwb3J0YWwtQW53ZW5kdW5nZW4u,props_eyJ0aGVtZSI6eyJtb2RlIjoiZGFyayIsImNvbG9ycyI6eyJwcmltYXJ5IjoiI0Q0QTI0QyJ9fX0,p_Ii9sZWl0ZmFlZGVuL2F1dGhlbnRpZml6aWVydW5nIg,s_FaeXduI94bo2XBs3.png"
---

## Authentifizierung

Wie Anwendungen sich ausweisen, welche Scopes es gibt und wie Sie Schlüssel tauschen, ohne den Betrieb zu unterbrechen.

## [Ein Header, mehr nicht](#ein-header-mehr-nicht)

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

```bash
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](#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](#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.

| Scope                   | Erlaubt                                                |
| :---------------------- | :----------------------------------------------------- |
| objekte:lesen           | Objekte und Medien abfragen                            |
| objekte:schreiben       | Objekte anlegen, ändern, archivieren, Medien hochladen |
| exposes:lesen           | Exposés und deren Status abfragen, PDF laden           |
| exposes:schreiben       | Exposés erzeugen und veröffentlichen                   |
| interessenten:lesen     | Interessenten, Suchprofile und Anfragen abfragen       |
| interessenten:schreiben | Interessenten pflegen, Anfragen bewerten               |
| termine:schreiben       | Besichtigungen anlegen, verschieben, absagen           |
| bewertungen:lesen       | Marktwertermittlungen und Vergleichswerte abfragen     |
| provisionen:lesen       | Abrechnungen und Rechnungen einsehen                   |

Fehlt ein Scope, antwortet die API mit `403`:

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

## [Schlüssel wechseln](#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](#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.