API-Schlüsselberechtigungen

API-Schlüsselberechtigungen begrenzen, was eine Softwareintegration innerhalb der Gruppe des Schlüssels tun darf. Sie identifizieren keine Person, gewähren keinen Zugriff auf andere Gruppen und ersetzen nicht den Rental-Tarif der Organisation. Menschliche Aktionen, die über eine launch_url geöffnet werden, erfordern weiterhin einen angemeldeten TrakarIA-Benutzer mit den passenden Gruppenberechtigungen.

Verwenden Sie für jedes System einen eigenen Schlüssel und erlauben Sie nur die Vorgänge, die dieses System tatsächlich ausführt. So können Sie eine Integration rotieren oder widerrufen, ohne andere zu unterbrechen, und begrenzen die Folgen eines offengelegten Schlüssels.

Berechtigungsreferenz

Jeder öffentliche API-Vorgang prüft genau eine Berechtigung. Eine Leseberechtigung gewährt niemals Schreibzugriff. Wenn unter API & Integrationen Schreibzugriff ausgewählt wird, wählt die Oberfläche auch die zugehörige Leseberechtigung aus, sofern vorhanden. Die Auswahl der Anlagenextraktion aktiviert außerdem den Lesezugriff auf Anlagen. Dies ist lediglich eine Hilfestellung der Oberfläche und keine Vererbung zwischen API-Berechtigungen.

Berechtigung	Erlaubt	Öffentliche Vorgänge
vehicles:read	Fahrzeuge in der Gruppe des Schlüssels abgleichen und lesen.	GET /v1/vehicles, GET /v1/vehicles/{vehicle_id}
vehicles:write	Ein Fahrzeug über die externe Kennung des Partners anlegen oder synchronisieren.	PUT /v1/vehicles/by-external/{external_id}
rentals:read	Rental-Vorgänge abgleichen und lesen sowie vorbereitete Inspektionen abrufen.	GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id}
rentals:write	Einen Rental-Vorgang anlegen, synchronisieren, ändern oder stornieren.	PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel
inspections:write	Eine Abfahrts- oder Rückgabeinspektion vorbereiten bzw. fortsetzen und den kurzlebigen Startlink erneuern. Die API darf damit keine menschliche Inspektion validieren.	POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch
evidence:read	Autorisierte originale Inspektionsnachweise einzeln oder als ZIP-Archiv auflisten und herunterladen.	GET /v1/inspections/{inspection_id}/evidence, GET /v1/evidence/{evidence_id}/content, GET /v1/inspections/{inspection_id}/evidence/archive, GET /v1/rentals/{rental_id}/evidence/archive
attachments:read	Vom Partner gelieferte private Dokumente auflisten und herunterladen.	GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content
attachments:write	Ein privates Dokument in einen Rental-Vorgang hochladen.	POST /v1/rentals/{rental_id}/attachments
attachments:extract	Eine kostenpflichtige Führerscheinextraktion für eine vorhandene Anlage starten. Extrahierte Werte müssen weiterhin geprüft werden.	POST /v1/attachments/{attachment_id}/extract
reports:read	Abfahrts- und Vergleichsberichte sowie deren PDFs ermitteln, lesen und herunterladen.	GET /v1/rentals/{rental_id}/report, GET /v1/rentals/{rental_id}/reports, GET /v1/reports/{report_id}, GET /v1/reports/{report_id}/pdf
events:read	Während eines Webhook-Ausfalls verpasste Lebenszyklusereignisse abgleichen.	GET /v1/events
jobs:read	Den sicheren Status und das Ergebnis eines asynchronen Vorgangs einschließlich Dokumentextraktion abfragen.	GET /v1/jobs/{job_id}

GET /v1/capabilities benötigt einen gültigen aktiven Schlüssel, aber keine zusätzliche Vorgangsberechtigung. Die Antwort enthält die wirksamen Produktfunktionen und Limits, jedoch keine vollständige Liste der Schlüsselberechtigungen.

Webhook-Ziele werden getrennt durch einen angemeldeten Gruppenadministrator unter API & Integrationen verwaltet. events:read steuert nur den Abgleich über GET /v1/events. Die Berechtigung erstellt kein Ziel, gewährt keinen Zugang zur Verwaltungsoberfläche und ersetzt nicht die Prüfung der Webhook-Signatur.

Häufige Berechtigungssätze

Integrationsbedarf	Empfohlenes Minimum
Verbindung und kommerzielle Funktionen prüfen	Gültiger Schlüssel; keine weitere Vorgangsberechtigung
Flotte und Reservierungen synchronisieren	vehicles:read, vehicles:write, rentals:read, rentals:write
Abfahrts- und Rückgabeinspektionen vorbereiten	Zusätzlich inspections:write
Inspektionsfotos und endgültige Berichte beziehen	Zusätzlich evidence:read, reports:read
Dokumente hochladen und einen Führerschein auslesen	Zusätzlich attachments:read, attachments:write, attachments:extract, jobs:read
Ereignisse nach einem Webhook-Ausfall nachholen	Zusätzlich events:read
Vollständigen Rental-Lebenszyklus umsetzen	Alle Berechtigungen auswählen, die Ihre gewählten Szenarien verwenden; Extraktions- oder Anlagenberechtigungen weglassen, wenn diese Funktionen nicht genutzt werden

Dies sind am Ablauf orientierte Empfehlungen. Die exakte Anforderung jedes Vorgangs steht als Required permission in der API-Referenz.

403 untersuchen

Fehlt einem gültigen Schlüssel die erforderliche Berechtigung, antwortet die API mit 403 und dem Code INSUFFICIENT_SCOPE. Die Problemantwort enthält die genau fehlende Berechtigung in errors[0].meta.required. Fügen Sie diese nur dann einem Ersatzschlüssel hinzu, wenn die Integration den Vorgang wirklich benötigt.

403 kann auch bedeuten, dass die Ressource außerhalb der Gruppe liegt, Organisation oder Funktion nicht verfügbar sind oder der Tarif den Vorgang nicht umfasst. Selbst alle Berechtigungen umgehen diese Prüfungen nicht. Siehe Authentifizierung und Zugriff sowie Synchronisierung und Fehler.