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#

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.