Permissions des clés API
Les permissions d’une clé API limitent les actions d’une intégration logicielle dans le groupe auquel appartient la clé. Elles n’identifient pas une personne, ne donnent pas accès à un autre groupe et ne remplacent pas l’abonnement Rental de l’organisation. Les actions humaines ouvertes via un launch_url exigent toujours un utilisateur TrakarIA connecté et autorisé dans le groupe.
Utilisez une clé distincte pour chaque système et accordez uniquement les opérations qu’il réalise. Vous pourrez ainsi renouveler ou révoquer une intégration sans interrompre les autres, tout en limitant l’impact d’une clé compromise.
Référence des permissions
Section intitulée « Référence des permissions »Chaque opération de l’API publique vérifie une permission précise. Une permission de lecture n’accorde jamais l’écriture. Dans API et intégrations, sélectionner l’écriture sélectionne aussi la lecture correspondante lorsqu’elle existe ; sélectionner l’extraction d’une pièce jointe sélectionne aussi sa lecture. C’est une aide de l’interface de création, pas une implication entre les permissions de l’API.
| Permission | Ce qu’elle autorise | Opérations publiques |
|---|---|---|
vehicles:read | Réconcilier et consulter les véhicules du groupe de la clé. | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | Créer ou synchroniser un véhicule à partir de l’identifiant externe du partenaire. | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | Réconcilier et consulter les dossiers Rental ainsi que leurs inspections préparées. | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | Créer, synchroniser, modifier ou annuler un dossier Rental. | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | Préparer ou reprendre une inspection de départ/retour et renouveler son lien de lancement temporaire. L’API ne peut pas valider l’inspection humaine. | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | Lister et télécharger les preuves originales autorisées, individuellement ou dans une archive ZIP. | 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 | Lister et télécharger les documents privés fournis par le partenaire. | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | Ajouter un document privé à un dossier Rental. | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | Lancer l’extraction facturable d’un permis de conduire déjà joint. Les données extraites doivent toujours être vérifiées. | POST /v1/attachments/{attachment_id}/extract |
reports:read | Découvrir, consulter et télécharger les rapports de départ/comparaison et leurs PDF. | 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 | Réconcilier les événements de cycle de vie manqués pendant une indisponibilité webhook. | GET /v1/events |
jobs:read | Consulter l’état et le résultat sûr d’une opération asynchrone, notamment l’extraction de document. | GET /v1/jobs/{job_id} |
GET /v1/capabilities nécessite une clé valide et active, mais aucune permission d’opération supplémentaire. Cette route indique les fonctionnalités et limites effectives ; elle ne fournit pas la liste complète des permissions de la clé.
Les destinations webhook sont gérées séparément dans API et intégrations par un administrateur de groupe connecté. events:read contrôle uniquement GET /v1/events pour la réconciliation ; cette permission ne crée pas de destination, ne donne pas accès à l’interface d’administration et ne remplace pas la vérification de la signature webhook.
Ensembles courants
Section intitulée « Ensembles courants »| Besoin d’intégration | Minimum conseillé |
|---|---|
| Vérifier la connexion et les capacités commerciales | Une clé valide ; aucune permission d’opération supplémentaire |
| Synchroniser la flotte et les réservations | vehicles:read, vehicles:write, rentals:read, rentals:write |
| Préparer les inspections de départ et de retour | Ajouter inspections:write |
| Consommer les photos d’inspection et rapports finaux | Ajouter evidence:read, reports:read |
| Ajouter des documents et extraire un permis | Ajouter attachments:read, attachments:write, attachments:extract, jobs:read |
| Récupérer les événements après une coupure webhook | Ajouter events:read |
| Implémenter tout le cycle Rental | Sélectionner chaque permission utilisée par les opérations de vos scénarios ; retirer les permissions d’extraction ou de pièces jointes si ces fonctions ne sont pas utilisées |
Ces propositions correspondent à des parcours courants. La permission exacte de chaque opération apparaît sous Required permission dans la référence API.
Diagnostiquer un 403
Section intitulée « Diagnostiquer un 403 »Lorsqu’une clé valide ne possède pas la permission nécessaire, l’API renvoie 403 avec le code INSUFFICIENT_SCOPE. La réponse indique la permission manquante dans errors[0].meta.required. Ajoutez-la à une clé de remplacement uniquement si l’intégration a réellement besoin de cette opération.
Un 403 peut aussi signaler une ressource hors du groupe de la clé, une organisation ou fonctionnalité indisponible, ou une opération absente de la formule commerciale. Accorder toutes les permissions ne contourne pas ces contrôles. Consultez Authentification et accès et Synchronisation et erreurs.