# Authentifizierung

> API-Schlüssel für Test- und Livedaten, Berechtigungen, Ratenlimits und sicherer Umgang.

Jede Anfrage an `/v1` und an den MCP-Server braucht einen API-Schlüssel in der Kopfzeile `Authorization`:

```http
GET /v1/organization HTTP/1.1
Host: api.ladehase.com
Authorization: Bearer lh_live_…
```

## Test- und Liveschlüssel

<table>
  <thead>
    <tr><th>Präfix</th><th>Daten</th><th>Zahlungen</th><th>Ladestationen</th></tr>
  </thead>
  <tbody>
    <tr><td>`lh_test_`</td><td>Testdaten (`livemode: false`)</td><td>Testzahlungen ohne echtes Geld</td><td>simulierte Testgeräte</td></tr>
    <tr><td>`lh_live_`</td><td>Livedaten (`livemode: true`)</td><td>echte Zahlungen über zahls.ch oder Freika</td><td>deine verbundenen Ladestationen</td></tr>
  </tbody>
</table>

Test- und Livedaten sind vollständig getrennt. Ein Testschlüssel sieht nie Livedaten und umgekehrt.

## Schlüssel erstellen

Im Dashboard unter «Entwickler» erstellst du Schlüssel und gibst ihnen einen Namen, damit du sie später wiedererkennst. Der vollständige Schlüssel wird nur einmal angezeigt. Speichere ihn in einem Passwortmanager oder in den Umgebungsvariablen deiner Anwendung.

> **Achtung:** Behandle Liveschlüssel wie Passwörter. Leg sie nie in den Quellcode, in Frontends oder in öffentliche Repositorys. Ist ein Schlüssel kompromittiert, widerrufe ihn sofort im Dashboard.

## Ratenlimit

Pro Schlüssel gilt ein Limit pro Minute (Standard 600 Anfragen). Jede Antwort enthält die Kopfzeilen `RateLimit-Limit`, `RateLimit-Remaining` und `RateLimit-Reset`. Wird das Limit überschritten, antwortet die API mit `429` und dem Code `rate_limited`. Die Kopfzeile `Retry-After` sagt, wie viele Sekunden du warten sollst.

## Organisationen

Ein Schlüssel gehört immer zu genau einer Organisation. Arbeitest du für mehrere Organisationen (zum Beispiel als Installateurin oder Installateur), erstellst du pro Organisation einen eigenen Schlüssel.

## Fehler bei der Anmeldung

<table>
  <thead>
    <tr><th>Status</th><th>Code</th><th>Bedeutung</th></tr>
  </thead>
  <tbody>
    <tr><td>401</td><td>`unauthorized`</td><td>Schlüssel fehlt, ist ungültig oder widerrufen.</td></tr>
    <tr><td>403</td><td>`forbidden`</td><td>Der Schlüssel darf diese Aktion nicht ausführen oder die Funktion ist für die Organisation nicht freigeschaltet.</td></tr>
  </tbody>
</table>