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 vehicle dataGET /vehicles, GET /vehicles/{id}
vehicles:writeCreate and update vehiclesPOST /vehicles, PUT /vehicles/{id}
inspections:readRead inspection templates and resultsGET /inspection-templates, GET /inspections
inspections:writeSubmit new inspectionsPOST /inspections

​
Requesting Scopes

When requesting an API key from your administrator, specify which scopes you need: 
vehicles: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
inspections:write → includes inspections:read
If you have write access, you automatically have read access for that resource.

​
Common Scope Combinations

​
Read-Only Integration

vehicles:read, inspections:read
Perfect for dashboards, reporting, and analytics.

​
Inspection Submission

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

​
Full Fleet Management

vehicles:write, inspections: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.