Skip to main content

​
Overview

API keys use scope-based permissions to control access to different resources and operations. Request only the scopes your integration needs following the principle of least privilege.

​
Available Scopes

ScopeDescriptionEndpoints
vehicles:readRead vehicles and legacy vehicle-adjacent resourcesGET /vehicles, GET /vehicles/{id}
vehicles:writeMutate vehicles and legacy vehicle-adjacent resourcesPOST, PUT, DELETE /vehicles*
vehicle-fields:readRead custom vehicle fields and field-derived vehicle statusesGET /vehicle-fields, GET /vehicle-fields/{id}/vehicles
vehicle-groups:readRead vehicle groupsGET /vehicle-groups, GET /vehicle-groups/{id}
vehicle-groups:writeMutate vehicle groupsPOST, PUT, DELETE /vehicle-groups*
inspections:readRead inspections and legacy template readsGET /inspections, GET /inspections/{id}
inspections:writeMutate inspections and legacy template writesPOST, PATCH, DELETE /inspections*
inspection-templates:readRead inspection templatesGET /inspection-templates, GET /inspection-templates/{id}
inspection-templates:writeMutate inspection templatesPOST, PUT, DELETE /inspection-templates*
damages:readRead damagesGET /damages, GET /damages/{id}
damages:writeMutate damagesPOST, PUT, DELETE /damages*
driver-assignments:readRead driver assignmentsGET /driver-assignments, GET /driver-assignments/{id}
driver-assignments:writeMutate driver assignmentsPOST, PATCH, DELETE /driver-assignments*

​
Requesting Scopes

When requesting an API key from your administrator, specify which scopes you need: 
vehicles:read, inspection-templates:read, inspections:write
Scopes are set during API key creation and cannot be changed. Create a new key to modify scopes.

​
Scope Validation

The API validates scopes on every request. If your key lacks required permissions, you’ll receive a 403 Forbidden error: 
{
  "errors": [{
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required": ["inspections:write"],
      "available": ["inspections:read"]
    }
  }]
}

​
Read vs Write Scopes

Read scopes allow retrieving data without modification:
  • Safe for analytics and reporting
  • Recommended for read-only integrations
Example use cases:
  • Dashboard displays
  • Reporting tools
  • Data synchronization (one-way)
Write scopes allow creating and modifying data:
  • Requires additional validation
  • Audit logged
Example use cases:
  • Inspection submission from devices
  • Vehicle data updates from TMS
  • Automated workflows

​
Scope Best Practices

Minimum Scopes

Request only the scopes your integration actually needs

Separate Keys

Use different API keys for read and write operations

Service-Specific

Create separate keys for different services or environments

Regular Audits

Review and revoke unused API keys regularly

​
Checking Your Scopes

You can check which scopes your API key has by examining the error response when accessing a forbidden endpoint: 
curl -X POST "https://api.inspecto.com/api/third-party/v1/inspections" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{}'
Response if you lack inspections:write: 
{
  "errors": [{
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required": ["inspections:write"],
      "available": ["vehicles:read", "inspections:read"]
    }
  }]
}

​
Scope Hierarchy

Some scopes imply others: 
vehicles:write → includes vehicles:read
vehicles:read → includes vehicle-fields:read
vehicle-groups:write → includes vehicle-groups:read
inspection-templates:write → includes inspection-templates:read
inspections:write → includes inspections:read
damages:write → includes damages:read
driver-assignments:write → includes driver-assignments:read
If you have write access, you automatically have read access for that resource.

​
Common Scope Combinations

​
Read-Only Integration

vehicles:read, vehicle-fields:read, vehicle-groups:read, inspection-templates:read, inspections:read, damages:read, driver-assignments:read
Perfect for dashboards, reporting, and analytics.

​
Inspection Submission

vehicles:read, inspection-templates:read, inspections:write
For devices or systems that submit inspections but don’t modify vehicle data.

​
Full Fleet Management

vehicles:write, vehicle-groups:write, inspection-templates:write, inspections:write, damages:write, driver-assignments:write
For TMS integrations that need full read/write access.

​
Future Scopes

Planned scopes for future releases:
ScopeStatusDescription
reports:readPlannedAccess custom reports
webhooks:managePlannedConfigure webhooks
users:readUnder ReviewRead user data
analytics:readUnder ReviewAccess analytics data
Subscribe to our changelog to be notified when new scopes are available.