API-Authentifizierung (TrackServiceKey)

TrackRoad-APIs verwenden einen API-Schlüssel mit dem Namen TrackServiceKey. Für REST senden Sie ihn als X-API-Key. Für SOAP senden Sie ihn in SessionIDHeader als SessionID.

TrackRoad-API-Authentifizierungsablauf mit TrackServiceKey als X-API-Key für REST und SessionIDHeader für SOAP
Authentifizierungsübersicht: TrackServiceKey ist Ihr API-Schlüssel — senden Sie ihn für REST als X-API-Key und für SOAP als SessionIDHeader/SessionID.

Benötigen Sie Endpunkte und Modelle?

Swagger bietet die vollständigen Anfrage- und Antwortschemata für Dispatch, Routes, Route, Geocode, Credit und Distance.

Swagger UI öffnen API-Referenz – Überblick

Inhaltsverzeichnis

  1. So funktioniert die Authentifizierung
  2. Ihren TrackServiceKey erzeugen
  3. REST-Authentifizierung (X-API-Key)
  4. SOAP-Authentifizierung (SessionIDHeader)
  5. Login / Logout (Legacy)
  6. Sicherheitsrichtlinien
  7. Häufige Fehler (401/403)
  8. Verwandte Endpunkte
  9. FAQ

So funktioniert die Authentifizierung#

TrackRoad verwendet für seine gesamte API eine einheitliche Authentifizierung: Ihren kontobezogenen TrackServiceKey.

  • Der TrackServiceKey wird in Ihrem TrackRoad-Konto erzeugt.
  • REST: Senden Sie ihn bei jeder Anfrage im Header X-API-Key.
  • SOAP: Senden Sie ihn bei jedem Aufruf im SessionIDHeader als SessionID.

Empfehlung für neue Integrationen: Verwenden Sie nach Möglichkeit REST und nutzen Sie SOAP nur für Legacy-Systeme.

Ihren TrackServiceKey erzeugen#

Bevor Sie die TrackRoad-API aufrufen, erstellen oder kopieren Sie Ihren Authentifizierungsschlüssel aus Ihrem Konto.

  1. Melden Sie sich in Ihrem TrackRoad-Konto an.
  2. Öffnen Sie Manage Users (oder die API-Einstellungen, falls vorhanden).
  3. Erzeugen oder kopieren Sie Ihren TrackServiceKey.
  4. Speichern Sie ihn ausschließlich sicher auf der Serverseite.

Wenn Sie Ihren TrackServiceKey nicht finden, wenden Sie sich an den TrackRoad-Support, um den API-Zugriff zu aktivieren oder zu bestätigen.

REST-Authentifizierung (X-API-Key)#

Senden Sie Ihren TrackServiceKey bei jeder REST-Anfrage an TrackRoad im Header X-API-Key.

curl -X POST "https://trackservice.trackroad.com/rest/credit" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY"

Bewahren Sie API-Schlüssel auf der Serverseite auf. Betten Sie den TrackServiceKey nicht in Browser-JavaScript, mobile Apps oder öffentlichen Client-Code ein.

SOAP-Authentifizierung (SessionIDHeader)#

SOAP-Aufrufe werden mit SessionIDHeader authentifiziert. Für TrackRoad-SOAP-Dienste senden Sie Ihren TrackServiceKey bei jeder Anfrage als Wert von SessionID.

Login und Logout können in älterer SOAP-Dokumentation noch erscheinen, sind jedoch für moderne Integrationen mit TrackServiceKey nicht erforderlich.

<soap:Header>
  <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
    <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
  </SessionIDHeader>
</soap:Header>

Login- / Logout-Endpunkte (Legacy)#

Login und Logout werden nur zur Abwärtskompatibilität beibehalten. Neue TrackRoad-Integrationen sollten sich mit TrackServiceKey authentifizieren: REST über X-API-Key und SOAP über SessionIDHeader.

Sicherheitsrichtlinien#

Der Schutz Ihres API-Schlüssels ist entscheidend für zuverlässige und sichere Produktivintegrationen.

  • API-Schlüssel niemals in Frontend-JavaScript offenlegen.
  • Verwenden Sie sichere Server-zu-Server- oder Backend-Integrationen.
  • Speichern Sie Schlüssel in Umgebungsvariablen, Secret-Managern oder geschützten Konfigurationsspeichern.
  • Rotieren Sie den Schlüssel sofort, wenn Sie eine Kompromittierung vermuten.
  • Protokollieren oder versenden Sie API-Schlüssel niemals im Klartext.

Häufige Fehler (401/403)#

Wenn die Authentifizierung fehlschlägt, prüfen Sie Headernamen, Schlüsselwert, Umgebung und Kontostatus.

  • 401 Unauthorized: fehlender oder ungültiger Schlüssel. Prüfen Sie bei REST X-API-Key. Prüfen Sie bei SOAP SessionIDHeader und SessionID.
  • 403 Forbidden: Der Schlüssel kann gültig sein, aber der Zugriff ist blockiert, abgelaufen oder durch Guthaben bzw. Berechtigungen eingeschränkt.

FAQ#

Wie authentifiziere ich TrackRoad-REST-API-Aufrufe?
Senden Sie Ihren TrackServiceKey bei jeder REST-Anfrage im Header X-API-Key.
Wie authentifiziere ich TrackRoad-SOAP-Aufrufe?
Für SOAP senden Sie Ihren TrackServiceKey im SessionIDHeader als SessionID bei jeder SOAP-Anfrage.
Benötige ich Login/Logout?
Nein. Login- und Logout-Endpunkte sind veraltet. Neue Integrationen sollten die Authentifizierung mit TrackServiceKey verwenden.
Warum erhalte ich 401 Unauthorized?
Häufige Ursachen sind ein fehlender Header X-API-Key, ein ungültiger Schlüssel, zusätzliche Leerzeichen oder die Verwendung der falschen Umgebung bzw. des falschen Hosts.

Nächster Schritt: einen Endpunkt testen

Sobald Sie Ihren TrackServiceKey haben, starten Sie mit Credit zur Validierung der Authentifizierung und fahren dann mit Geocode, Route, Routes oder Dispatch fort.

Credit prüfen Zu Dispatch