# Authentifizierung

<Lead>
Die Plattform-API authentifiziert über **workspace-gebundene API-Keys**. Jeder Key gehört zu genau einem Workspace, hat einen Geltungsbereich und wird als Bearer-Token mitgesendet. Diese Seite beschreibt das Modell und den heutigen Beta-Stand.
</Lead>

<BetaNotice>
Die API-Key-Verwaltung unter **Einstellungen > API** ist eine Beta-Fläche mit eingeschränktem Funktionsumfang. Der vollständige Lebenszyklus (Scopes, einmalige Anzeige, Rotation, Nutzungs-Logs) erscheint zusammen mit der öffentlichen REST-API. Webhook-Signaturen (siehe unten) sind davon unabhängig und heute produktiv.
</BetaNotice>

## Das Modell

<DefinitionList>
  <DefItem term="Workspace-Bindung">
    Ein API-Key gehört zu genau einem Workspace und kann ausschließlich auf dessen Daten zugreifen. Mandanten-übergreifende Keys gibt es nicht.
  </DefItem>
  <DefItem term="Geltungsbereich (Scope)">
    Beim Erstellen wählst du zwischen <strong>Lesend</strong> (Daten abrufen, nichts schreiben oder löschen) und <strong>Vollständig</strong> (lesen, schreiben, löschen im Rahmen der Rechte der erstellenden Person).
  </DefItem>
  <DefItem term="Einmalige Anzeige">
    Der Klartext-Key wird genau einmal angezeigt: direkt nach dem Erstellen. Danach bleiben nur Name und die letzten vier Zeichen sichtbar. Verlierst du den Key, erstellst du einen neuen und widerrufst den alten.
  </DefItem>
  <DefItem term="Wer darf Keys verwalten?">
    Nur Nutzer:innen mit der Rolle Admin (oder die Workspace-Inhaber:in). Alle Key-Aktionen werden im Audit-Log protokolliert.
  </DefItem>
</DefinitionList>

## Verwendung im Request

Der Key wird als Bearer-Token im `Authorization`-Header gesendet. Anfragen laufen ausschließlich über HTTPS; unverschlüsselte Anfragen werden abgelehnt.

<RequestExample method="GET" path="/api/v1/properties" language="HTTP">
{`GET /api/v1/properties HTTP/1.1
Host: api.reosa.de
Authorization: Bearer <dein-api-key>
Content-Type: application/json`}
</RequestExample>

Antworten auf fehlende oder ungültige Authentifizierung:

| Status | Bedeutung |
|---|---|
| `401 Unauthorized` | Kein Key mitgesendet, Key ungültig oder widerrufen |
| `403 Forbidden` | Key gültig, aber der Geltungsbereich erlaubt die Aktion nicht |

## Sicherheitsregeln

<Warning title="Keys sind Geheimnisse">
Behandle API-Keys wie Passwörter: niemals in Quellcode oder Versionsverwaltung, ein eigener Key pro Integration mit kleinstmöglichem Geltungsbereich, ungenutzte Keys widerrufen. Bei Verdacht auf Kompromittierung: neuen Key erstellen, Integration umstellen, alten Key widerrufen.
</Warning>

Eine Schritt-für-Schritt-Anleitung für Endnutzer:innen steht im Help-Center: [API-Key erstellen](/help/howto/create-api-key).

## Webhook-Signaturen

Webhooks nutzen keine API-Keys, sondern ein eigenes Signatur-Verfahren nach Standard-Webhooks: Jede Zustellung ist mit einem endpoint-eigenen Secret HMAC-signiert, das du beim Anlegen des Endpoints genau einmal siehst. Details und Prüf-Anleitung: [Webhooks](/api/webhooks).