Authentifizierung¶

Alle Zugriffe auf die calServer REST-API erfordern eine Authentifizierung. Die API unterstuetzt zwei Authentifizierungsmethoden — je nach API-Version.

API v2 — Bearer Token (Beta — calServer 6.0)¶

In Entwicklung

API v2 befindet sich in aktiver Entwicklung fuer calServer 6.0 und ist noch nicht produktionsreif.

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

Token erzeugen¶

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

Antwort:

{
  "token": "1|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

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 (API v2)¶

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

API v1 — Header-basierte Authentifizierung¶

Die Legacy-API v1 verwendet drei HTTP-Header fuer die Authentifizierung.

Erforderliche Header¶

Header	Beschreibung
`HTTP_X_REST_USERNAME`	Benutzername des API-Benutzers
`HTTP_X_REST_PASSWORD`	Passwort des API-Benutzers
`HTTP_X_REST_API_KEY`	API-Schluessel (im Benutzerprofil generiert)

Alle drei Header muessen in jeder Anfrage vorhanden sein. Fehlt einer der Header oder sind die Werte ungueltig, antwortet die API mit einem Authentifizierungsfehler.

Beispielanfrage (API v1)¶

curl -X GET "https://ihre-instanz.example.com/api/inventory" \
  -H "HTTP_X_REST_USERNAME: IhrBenutzername" \
  -H "HTTP_X_REST_PASSWORD: IhrPasswort" \
  -H "HTTP_X_REST_API_KEY: IhrAPIKey"

API-Schluessel erstellen¶

Melden Sie sich in calServer an
Oeffnen Sie Ihr Benutzerprofil
Navigieren Sie zum Bereich API-Schluessel
Erzeugen Sie einen neuen Schluessel

Der API-Schluessel wird in der Tabelle FrontendUserKey gespeichert und ist dem jeweiligen Benutzerkonto zugeordnet.

Fehlercodes¶

HTTP-Status	Bedeutung
`401 Unauthorized`	Fehlende oder ungueltige Anmeldedaten
`403 Forbidden`	Authentifizierung erfolgreich, aber fehlende Berechtigung
`404 Not Found`	Angeforderter Endpunkt oder Datensatz existiert nicht
`422 Unprocessable Entity`	Validierungsfehler (nur API v2)
`500 Internal Server Error`	Serverfehler — pruefen Sie die Anwendungslogs

Hinweise¶

Uebertragen Sie Anmeldedaten ausschliesslich ueber HTTPS
API-Schluessel und Tokens koennen jederzeit widerrufen und neu erzeugt werden
Fuer automatisierte Systeme empfiehlt sich ein dediziertes Benutzerkonto mit eingeschraenkter Rolle
Die Berechtigungspruefung unterliegt denselben Regeln wie die Weboberflaeche (RBAC)