Authentifizierung — API v2¶

Die API v2 verwendet Bearer-Token-Authentifizierung via Laravel Sanctum.

Token erstellen¶

POST /auth/token ist der Weg für programmatische Clients und verlangt neben E-Mail und Passwort den API-Key des Benutzers im Header X-REST-API-KEY:

curl -X POST "https://ihre-instanz.example.com/api/v2/auth/token" \
  -H "Content-Type: application/json" \
  -H "X-REST-API-KEY: {api-key-des-benutzers}" \
  -d '{
    "email": "user@example.com",
    "password": "IhrPasswort",
    "token_name": "api-client"
  }'

Antwort:

{
  "data": {
    "token": "1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "type": "bearer"
  },
  "meta": { "api_version": "2.0" }
}

Der API-Key steht unter Administration → Benutzer → [Benutzer] → API-Key; neue Benutzer bekommen ihn automatisch. Fehlt der Header, antwortet der Endpunkt mit 422, bei falschem Key mit 401 Invalid API key.

Interaktiver Login

Für den Login aus einer Oberfläche gibt es POST /auth/login mit {"email": …, "password": …} — ohne API-Key, dafür mit Passwort-Ablauf- und Sperr-Logik. /auth/token ist für Integrationen gedacht.

Der Benutzer braucht in beiden Fällen die Operation using_API, sonst antwortet jeder API-Aufruf mit 403.

Langlebiges API-Token (ohne Passwort)¶

Für dauerhafte Integrationen ist der Umweg über /auth/token unnötig: ein Administrator stellt unter Administration → Benutzer → [Benutzer] → API-Token ein Token aus, das direkt als Bearer verwendet wird.

Das ist der bevorzugte Weg für Maschinen-zu-Maschinen-Zugriffe, denn die Gegenstelle speichert dann nur diesen einen Wert — kein Passwort, kein API-Key. Das Passwort des Service-Benutzers ist zugleich ein Oberflächen-Login, ein Leak der Gegenstellen-Konfiguration gibt damit sonst mehr her als den API-Zugriff.

	API-Token	API-Key + Login
Zu hinterlegende Werte	1 (Token)	3 (Key, E-Mail, Passwort)
Passwort bei der Gegenstelle	nein	ja
Einzeln widerrufbar	ja	nein (Key gilt für alle)
Ablaufdatum	optional	keins
Erneuerung durch den Client	nicht möglich	automatisch bei `401`

Ein Token trägt die vollen Rechte seines Benutzers — Sanctum-Abilities werden nicht ausgewertet, die Rolle ist die Berechtigungsgrenze. Der Klartext wird genau einmal bei der Ausgabe angezeigt (gespeichert wird nur ein SHA-256-Hash); ein neues Token entwertet bestehende nicht, verloren gegangene lassen sich also gefahrlos ersetzen. Beim Löschen eines Benutzers werden seine Token und sein API-Key sofort ungültig.

Token verwenden¶

Der Token wird als Authorization-Header in allen nachfolgenden Anfragen mitgesendet:

curl -X GET "https://ihre-instanz.example.com/api/v2/inventories" \
  -H "Authorization: Bearer 1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Berechtigungen¶

Permission	Beschreibung
`inventory_view`	Inventar lesen
`inventory_edit`	Inventar erstellen/bearbeiten, Kategorien verwalten
`inventory_delete`	Inventar löschen
`calibration_view`	Kalibrierungen lesen
`calibration_edit`	Kalibrierungen erstellen/bearbeiten
`customers_view`	Kunden lesen
`customers_edit`	Kunden erstellen/bearbeiten

Fehlercodes¶

HTTP-Status	Bedeutung
`401 Unauthorized`	Fehlende oder ungültige Anmeldedaten
`403 Forbidden`	Authentifizierung erfolgreich, aber fehlende Berechtigung
`404 Not Found`	Angeforderter Endpunkt oder Datensatz existiert nicht
`422 Unprocessable Entity`	Validierungsfehler
`500 Internal Server Error`	Serverfehler — prüfen Sie die Anwendungslogs

Hinweise¶

Übertragen Sie Anmeldedaten ausschließlich über HTTPS
Tokens können jederzeit widerrufen und neu erstellt werden
Für automatisierte Systeme empfiehlt sich ein dediziertes Benutzerkonto mit eingeschränkter Rolle
Die Berechtigungsprüfung unterliegt denselben Regeln wie die Weboberfläche (RBAC)