API key permissions
API key permissions limit what one software integration can do inside the key’s group. They do not identify a person, grant access to another group, or replace the organization’s Rental subscription. Human actions opened through a launch_url still require a signed-in TrakarIA user with the appropriate group permissions.
Use a separate key for each system and grant only the operations that system performs. This lets you rotate or revoke one integration without interrupting another and limits the impact of a leaked credential.
Permission reference
Section titled “Permission reference”Every public API operation checks one exact permission. A read permission never grants write access. In API & integrations, selecting write access also selects the matching read permission when one exists; selecting attachment extraction also selects attachment read access. This is a convenience of the key-creation interface, not an implication between API permissions.
| Permission | What it allows | Public operations |
|---|---|---|
vehicles:read | Reconcile and read vehicles in the key’s group. | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | Create or synchronize a vehicle by the partner’s external ID. | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | Reconcile and read Rental dossiers and read their prepared inspections. | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | Create, synchronize, update or cancel a Rental dossier. | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | Prepare or resume a departure/return inspection and renew its short-lived launch link. It does not let the API validate the human inspection. | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | List and download authorized original inspection evidence, individually or as a ZIP archive. | 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 | List and download private documents supplied by the partner. | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | Upload a private document to a Rental dossier. | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | Start billable driver-license extraction on an existing attachment. Extracted values still require review. | POST /v1/attachments/{attachment_id}/extract |
reports:read | Discover, read and download departure/comparison reports and their PDFs. | 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 | Reconcile lifecycle events missed during webhook downtime. | GET /v1/events |
jobs:read | Poll the safe status and result of an asynchronous operation, including document extraction. | GET /v1/jobs/{job_id} |
GET /v1/capabilities requires a valid active key but no additional operation permission. It reports effective product features and limits; it is not a complete list of the key’s permissions.
Webhook destinations are managed separately by a signed-in group administrator in API & integrations. events:read controls only GET /v1/events for reconciliation; it does not create a destination, grant access to the administration interface, or replace webhook signature verification.
Common permission sets
Section titled “Common permission sets”| Integration need | Suggested minimum |
|---|---|
| Check connectivity and commercial capabilities | A valid key; no additional operation permission |
| Synchronize fleet and reservations | vehicles:read, vehicles:write, rentals:read, rentals:write |
| Prepare departure and return inspections | Add inspections:write |
| Consume inspection photos and final reports | Add evidence:read, reports:read |
| Upload documents and extract a driving licence | Add attachments:read, attachments:write, attachments:extract, jobs:read |
| Recover events after webhook downtime | Add events:read |
| Implement the complete Rental lifecycle | Select every permission used by the operations in your chosen scenarios; remove extraction or attachment permissions when those features are not used |
These are workflow-oriented suggestions. The exact requirement for each operation is shown as Required permission in the API reference.
Diagnosing a 403
Section titled “Diagnosing a 403”When a valid key lacks the required permission, the API returns 403 with code INSUFFICIENT_SCOPE. The problem response includes the exact missing permission in errors[0].meta.required. Add that permission to a replacement key only if the integration genuinely needs the operation.
A 403 can also mean that the resource is outside the key’s group, the organization or feature is unavailable, or the commercial plan does not include the operation. Granting every permission does not bypass those checks. See authentication and access and synchronization and errors.