Rechten van API-sleutels
API-sleutelrechten beperken wat één software-integratie binnen de groep van de sleutel kan doen. Ze identificeren geen persoon, geven geen toegang tot een andere groep en vervangen het Rental-abonnement van de organisatie niet. Menselijke handelingen via een launch_url vereisen nog steeds een aangemelde TrakarIA-gebruiker met passende groepsrechten.
Gebruik per systeem een afzonderlijke sleutel en verleen alleen de werkelijk gebruikte bewerkingen. Zo kun je één integratie roteren of intrekken zonder andere te onderbreken en beperk je de gevolgen van een gelekte credential.
Rechtenreferentie
Section titled “Rechtenreferentie”Iedere publieke API-bewerking controleert één exact recht. Leesrecht verleent nooit schrijfrecht. In API & integraties selecteert schrijfrecht ook het bijbehorende leesrecht wanneer dat bestaat; extractie van bijlagen selecteert ook het leesrecht voor bijlagen. Dit is alleen gebruiksgemak in de interface, geen implicatie tussen API-rechten.
| Recht | Wat het toestaat | Publieke bewerkingen |
|---|---|---|
vehicles:read | Voertuigen in de groep lezen en reconciliëren. | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | Een voertuig maken of synchroniseren via het externe ID van je systeem. | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | Rental-dossiers en voorbereide inspecties lezen en reconciliëren. | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | Een Rental-dossier maken, synchroniseren, bijwerken of annuleren. | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | Een vertrek- of retourinspectie voorbereiden/hervatten en de tijdelijke startlink vernieuwen. De API kan de menselijke inspectie hiermee niet valideren. | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | Geautoriseerd origineel inspectiebewijs afzonderlijk of als ZIP lezen en downloaden. | 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 | Privédocumenten van je software lezen en downloaden. | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | Een privédocument aan een Rental-dossier toevoegen. | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | Betaalde extractie van een bestaand rijbewijs starten. De waarden blijven te beoordelen voorstellen. | POST /v1/attachments/{attachment_id}/extract |
reports:read | Vertrek- en vergelijkingsrapporten en hun PDF’s vinden, lezen en downloaden. | 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 | Levenscyclusgebeurtenissen herstellen die tijdens webhookuitval zijn gemist. | GET /v1/events |
jobs:read | Veilige status en resultaat van een asynchrone bewerking opvragen, waaronder documentextractie. | GET /v1/jobs/{job_id} |
GET /v1/capabilities vereist een geldige actieve sleutel maar geen extra bewerkingsrecht. Het antwoord bevat effectieve productfuncties en limieten, niet de volledige rechtenlijst van de sleutel.
Een aangemelde groepsbeheerder beheert webhookbestemmingen afzonderlijk. events:read bestuurt alleen herstel via GET /v1/events; het maakt geen bestemming, verleent geen beheertoegang en vervangt handtekeningverificatie niet.
Gebruikelijke rechtensets
Section titled “Gebruikelijke rechtensets”| Integratiebehoefte | Aanbevolen minimum |
|---|---|
| Verbinding en commerciële mogelijkheden controleren | Een geldige sleutel, zonder aanvullend bewerkingsrecht |
| Wagenpark en reserveringen synchroniseren | vehicles:read, vehicles:write, rentals:read, rentals:write |
| Vertrek- en retourinspecties voorbereiden | Voeg inspections:write toe |
| Inspectiefoto’s en eindrapporten verwerken | Voeg evidence:read, reports:read toe |
| Documenten uploaden en een rijbewijs uitlezen | Voeg attachments:read, attachments:write, attachments:extract, jobs:read toe |
| Gebeurtenissen na webhookuitval herstellen | Voeg events:read toe |
| De volledige Rental-levenscyclus implementeren | Selecteer alle rechten van de gekozen scenario’s; laat extractie- en bijlagerechten weg als je die functies niet gebruikt |
Het exacte recht van iedere bewerking staat als Required permission in de API-referentie.
Een 403 diagnosticeren
Section titled “Een 403 diagnosticeren”Wanneer een geldige sleutel het vereiste recht mist, retourneert de API 403 met code INSUFFICIENT_SCOPE. Het ontbrekende recht staat in errors[0].meta.required. Voeg het alleen aan een vervangende sleutel toe als de integratie die bewerking werkelijk nodig heeft.
Een 403 kan ook betekenen dat de resource buiten de groep valt, de organisatie of functie niet beschikbaar is, of het abonnement de bewerking niet omvat. Alle rechten verlenen omzeilt die controles niet. Zie authenticatie en toegang en synchronisatie en fouten.