#Anmeldung und Rechte

Jeder Aufruf an /api/v1/extern trägt eine Anmeldung. Sie bestimmt Ihr Konto, die Umgebung (Echtbetrieb oder Sandbox) und was der Aufruf darf.

#Zwei Wege

Beide führen an dieselben Endpunkte mit denselben Rechten. Eine Anmeldung des Portals (Sitzungs-Token) gilt an der Schnittstelle nicht — die Schnittstelle ist für Systeme, das Portal für Menschen.

#OAuth 2.0 Client Credentials

Ein OAuth-Client hat eine Client-Kennung (lcc_…) und ein Secret. Damit holt Ihr System ein Zugriffstoken:

curl https://api.logicar.cloud/api/v1/extern/oauth/token \
  -u "lcc_3f9a1c2b7d4e4f60a8b9c0d1e2f3a4b5:lc_live_…" \
  -d grant_type=client_credentials \
  --data-urlencode "scope=orders:read orders:write"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "orders:read orders:write"
}

• Kennung und Secret gehen per HTTP Basic (-u) oder als client_id und client_secret im Rumpf (application/x-www-form-urlencoded) — nicht beides zugleich.
• scope ist freiwillig. Damit beschränken Sie das Token auf einen Teil der Rechte des Zugangs; ohne scope bekommt es alle.
• Das Token gilt eine Stunde. Holen Sie rechtzeitig ein neues — spätestens, wenn ein Aufruf 401 TOKEN_EXPIRED antwortet. Token lassen sich nicht verlängern, und es gibt kein Refresh-Token.
• Token-Abrufe sind gedrosselt (Grenzen): holen Sie eines und nutzen Sie es, statt je Aufruf ein neues.

Wenn der Token-Endpunkt ablehnt, antwortet er im Format von OAuth 2.0 ({ "error", "error_description" }):

#API-Schlüssel

Jede Antwort nennt die Umgebung im Kopf X-LogiCar-Environment (production oder sandbox). Ein Testschlüssel, der versehentlich in der Produktionskonfiguration steht, fällt so auch im Protokoll Ihres Systems auf.

Das Secret eines OAuth-Clients ist kein API-Schlüssel: als Schlüssel geschickt, antwortet die Schnittstelle 401 ACCESS_TOKEN_REQUIRED.

#Rechte

Jeder Zugang hat eigene Rechte. Kein Recht schließt ein anderes ein — wer anlegen und lesen soll, bekommt orders:write und orders:read.

GET /me braucht kein Recht: es zeigt, mit welchem Zugang, in welcher Umgebung und mit welchen Rechten Ihr System ankommt — der erste Aufruf jeder neuen Anbindung. Fehlt einem Aufruf ein Recht, antwortet die Schnittstelle 403 INSUFFICIENT_SCOPE und nennt es in details.required.

#Zugänge verwalten

Zugänge verwaltet der Administrator Ihres Kontos im Portal unter Einstellungen → API-Zugang:

• Anlegen: Name (etwa „SAP Produktion“), Umgebung, Art (API-Schlüssel oder OAuth-Client) und Rechte, auf Wunsch ein Ablaufdatum. Schlüssel bzw. Secret erscheinen einmal im Klartext; gespeichert wird nur eine Prüfsumme.
• Rechte ändern, sperren, freigeben: wirkt sofort — auch für Token, die schon ausgegeben sind.
• Erneuern: legt einen neuen Zugang mit denselben Rechten an. Der alte gilt noch 24 Stunden, damit Sie ihn ohne Lücke austauschen können.
• Widerrufen: endgültig und sofort. Aufrufe damit bekommen 401 INVALID_CREDENTIALS.

Mehrere Zugänge je Konto sind der Normalfall: je System einer, jeder mit genau den Rechten, die es braucht. Dann lässt sich einer zurückziehen, ohne die anderen zu stören. Die Liste zeigt je Zugang, wann er zuletzt benutzt wurde.

Den Echtbetrieb der Schnittstelle schaltet LOGICAR für Ihr Konto frei. Bis dahin antworten Zugänge des Echtbetriebs 403 FEATURE_NOT_ENABLED; die Sandbox steht Ihnen sofort offen.

#Aufbewahren

• Nur auf dem Server verwenden — nie in einer Web-Oberfläche, einer App oder einem öffentlichen Repository.
• In einer Umgebungsvariablen oder einem Secret-Store ablegen, nicht im Quelltext.
• Ist ein Schlüssel nach außen gelangt: sofort widerrufen und einen neuen anlegen. Sagen Sie uns Bescheid, wenn Sie nicht sicher sind, ob er benutzt wurde.

#Wenn die Anmeldung scheitert

Alle Codes stehen unter Fehler und Grenzen.