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
Abschnitt betitelt „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
Abschnitt betitelt „Zusätzliche Header“| Header | Beschreibung |
|---|---|
X-Tenant-ID | Wählt den effektiven Tenant-Kontext für JWT-Requests und benutzergebundene API Keys ohne feste Tenant-Bindung. 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. |
Bei JWTs und API Keys ohne feste Tenant-Bindung wird ohne X-Tenant-ID kein Tenant automatisch ausgewählt. Endpunkte, die einen Tenant-Kontext voraussetzen, lehnen solche Anfragen ab. Die Auswahl erfordert eine aktive Mitgliedschaft im gewünschten Tenant; Superuser können auch ohne Mitgliedschaft einen aktiven Tenant auswählen.
API-Schlüsselverwaltung
Abschnitt betitelt „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; Standardwert ist true. Mit false wird ein benutzergebundener Key ohne feste Tenant-Bindung erstellt. |
tenant_id | Tenant-ID für tenant-gebundene Keys. Falls nicht angegeben, wird der aktuelle Tenant-Kontext verwendet. Bei tenant_bound: false muss das Feld entfallen oder null sein. |
user_id | Bei tenant-gebundenen Keys: weglassen, um den aktuellen Benutzer als Eigentümer zu verwenden; explizit null senden, um einen Key ohne Benutzerbindung zu erstellen. Bei tenant_bound: false wird ohne Benutzer-ID der aktuelle Benutzer verwendet. |
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
Abschnitt betitelt „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.
Angeforderte Key-Permissions müssen für die Erstellung erlaubt sein. Bei tenant-gebundenen Keys mit Benutzerbindung werden zusätzlich die Permissions des vorgesehenen Eigentümers berücksichtigt. Unbekannte Permissions führen zu 400 Bad Request; Permissions außerhalb des erlaubten Umfangs führen zu 403 Forbidden. Die API lehnt die Erstellung ab und kürzt die angeforderte Liste nicht automatisch.
Administrative Optionen
Abschnitt betitelt „Administrative Optionen“Superuser können mit dem Header X-Impersonate-User-ID einen anderen aktiven Benutzer als effektiven Benutzer auswählen. Ohne Superuser-Berechtigung wird die Anfrage mit 403 Forbidden abgelehnt. Die Tenant-Auswahl wird weiterhin geprüft.
Beim Erstellen eines API Keys ist außerdem das Body-Feld is_superuser verfügbar; der Standardwert ist false. Nur Superuser dürfen es auf true setzen, und der Key muss an einen Benutzer gebunden sein. Für Superuser-Zugriff in einem Tenant-Kontext müssen sowohl der Key entsprechend markiert als auch sein Eigentümer ein Superuser sein.
Sicherheit
Abschnitt betitelt „Sicherheit“API Keys sind vertrauliche Zugangsdaten. Teile sie niemals öffentlich und speichere sie nicht in öffentlichen Repositories.