# API-Key erstellen

## Voraussetzung

API-Keys können nur von Nutzern mit der Rolle **Admin** erstellt werden. Die API ist ab dem **Standard-Tarif** verfügbar. Im Compact-Tarif ist der API-Zugang nicht freigeschaltet.

---

## API-Key erstellen

1. Gehe zu **Einstellungen > Entwickler > API-Keys**.
2. Klicke auf **Neuen API-Key erstellen**.
3. Vergib einen beschreibenden Namen, zum Beispiel "CRM-Integration" oder "Sync-Skript Büro".
4. Wähle den **Geltungsbereich** (Scope):
   - *Lesend:* Darf Daten abrufen, aber keine Daten schreiben oder löschen.
   - *Vollständig:* Darf lesen, schreiben und löschen (entspricht dem Zugriffsrecht der erstellenden Person).
5. Klicke auf **Key erstellen**.

Der generierte Key wird **einmalig im Klartext angezeigt**. Kopiere ihn sofort und speichere ihn sicher (zum Beispiel in einem Passwort-Manager). Nach dem Schließen des Dialogs kann der Key nicht mehr eingesehen werden. Nur der Name und die letzten vier Zeichen bleiben sichtbar.

---

## Key im HTTP-Request verwenden

Sende den API-Key als Bearer-Token im `Authorization`-Header:

```
GET /api/v1/credentials HTTP/1.1
Host: api.reosa.de
Authorization: Bearer <dein-api-key>
Content-Type: application/json
```

Ersetze `<dein-api-key>` durch den vollständigen Key-String. Verwende ausschließlich HTTPS. Anfragen über HTTP werden abgelehnt.

---

## Rate-Limits

| Tarif | Anfragen pro Minute | Anfragen pro Tag |
|---|---|---|
| Standard | 60 | 5.000 |
| Max | 300 | 50.000 |

Bei Überschreitung des Limits antwortet die API mit dem HTTP-Status `429 Too Many Requests`. Der `Retry-After`-Header enthält die Anzahl der Sekunden bis zum nächsten erlaubten Request.

---

## Key rotieren oder widerrufen

**Rotieren:** Wenn du den Verdacht hast, dass ein Key kompromittiert wurde, erstelle sofort einen neuen Key und widerrufe den alten. Zwischen den beiden Schritten gibt es ein kurzes Zeitfenster, in dem beide Keys aktiv sind. So kannst du Integrationen ohne Ausfallzeit umstellen.

**Widerrufen:** Klicke in der Key-Liste auf die Drei-Punkte-Schaltfläche neben dem Key und wähle **Key widerrufen**. Der Key ist danach sofort ungültig. Anfragen mit dem widerrufenen Key erhalten den HTTP-Status `401 Unauthorized`.

---

## Sicherheitshinweise

- Speichere API-Keys **niemals** im Quellcode oder in Versionsverwaltungssystemen.
- Verwende für jede Integration einen separaten Key mit dem kleinstmöglichen Geltungsbereich.
- Überwache die Key-Nutzung unter *Einstellungen > Entwickler > API-Logs* und widerrufe Keys, die nicht mehr verwendet werden.
- Alle API-Anfragen werden im Audit-Log des Tenants protokolliert.