Authentifizierung

Die LIVOI API erwartet für geschützte Endpunkte einen gültigen Bearer-Token im Authorization-Header:

Authorization: Bearer <TOKEN>

Der Bearer-Wert kann zwei Arten von Zugangsdaten enthalten:

ein JWT, wenn der Token aus drei durch Punkte getrennten Segmenten besteht
einen LIVOI API Key, wenn der Token kein JWT ist

API Keys werden nicht über einen eigenen Header gesendet. Verwende auch für API Keys immer:

Authorization: Bearer <API_KEY>

Fehlt der Header oder ist das Format ungültig, wird die Anfrage abgelehnt.

API-Key-Format

API Keys folgen intern diesem Format:

<kind>_<instance>_<key_id>_<marker>.<secret>

Die Bestandteile dienen nur zur Orientierung:

Feld	Werte
`kind`	`pk`, `sk`, `wk`
`instance`	`prod`, `staging`, `dev`, `test`, `local`

Clients sollten API Keys als opaque Secret behandeln und das Format nicht parsen.

Zusätzliche Header

Header	Beschreibung
`X-Tenant-ID`	Wählt den effektiven Tenant-Kontext für JWT-Requests. Bei tenant-gebundenen API Keys muss der Wert zur Key-Bindung passen oder entfallen.
`X-Request-ID`	Optionaler Client-Request-Identifier. Wenn er fehlt oder ungültig ist, erzeugt das Backend selbst eine Request-ID.

API-Schlüsselverwaltung

API-Schlüssel können über das LIVOI Dashboard verwaltet werden. Zusätzlich stellt die API diese Endpunkte bereit:

Methode	Pfad	Zweck
`GET`	`/api/v1/auth/me`	Aktuellen Auth-Kontext abrufen
`POST`	`/api/v1/auth/api-keys/`	Neuen API Key erstellen
`GET`	`/api/v1/auth/api-keys/`	API Keys auflisten
`DELETE`	`/api/v1/auth/api-keys/{api_key_id}`	API Key löschen
`POST`	`/api/v1/auth/api-keys/{api_key_id}/revoke`	API Key widerrufen

Beim Erstellen eines API Keys sind unter anderem diese Body-Felder relevant:

Feld	Beschreibung
`name`	Anzeigename des Keys
`description`	Optionale Beschreibung
`kind`	Key-Art, z. B. `pk`, `sk` oder `wk`
`instance`	Zielinstanz, z. B. `prod`, `staging`, `dev`, `test` oder `local`
`tenant_bound`	Bindet den Key an einen Tenant-Kontext
`tenant_id`	Tenant-ID für tenant-gebundene Keys
`user_id`	Benutzerbindung, falls der Key für einen bestimmten Benutzer erstellt wird
`expires_at`	Optionales Ablaufdatum
`permissions`	Berechtigungen, die der Key erhalten soll

Das Klartext-Feld api_key wird nur bei der Erstellung zurückgegeben. Danach ist der vollständige Secret-Wert nicht erneut abrufbar.

Berechtigungen

Die API prüft konkrete Permissions, statt nur eine allgemeine Administratorrolle vorauszusetzen. Für API-Key-Verwaltung sind unter anderem Permissions wie api_keys.create, api_keys.create.own und api_keys.create.any relevant.

Neue Key-Permissions werden auf die effektiv erlaubten Permissions des anfragenden Kontexts begrenzt. Ein Benutzer oder Key kann also keine weitergehenden Rechte vergeben, als der eigene Kontext erlaubt.

Sicherheit

API Keys sind vertrauliche Zugangsdaten. Teile sie niemals öffentlich und speichere sie nicht in öffentlichen Repositories.