REST API (v1)

Authentication

All endpoints require an Authorization: Bearer <api-key> header. Generate a key in Settings → API keys. The key is shown once on creation — copy it immediately; we store only a SHA-256 hash.

Each tenant has its own keys. The tenant id is inferred from the key, so you never need to send a tenant header — Fleetonomy will reject any request whose key is for a different tenant than the resource it targets.

Rate limits

Rate limits are enforced per key. Defaults scale with the tenant's plan:

• Trial: 60 requests / minute
• Starter: 120 requests / minute
• Professional: 600 requests / minute
• Enterprise: 6000 requests / minute (configurable)

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. 429 Too Many Requests sets a Retry-After header (seconds).

Response envelope

// Success
{ "ok": true, "data": { ... } }

// Error
{
  "ok": false,
  "error": {
    "code": "invalid_body",
    "message": "Field 'registration' is required",
    "details": { ... }
  }
}

Resources

Vehicles

GET /api/v1/vehicles — paginated list, query params: cursor, limit (1–100), status.

curl -H "Authorization: Bearer fln_live_..." \
     "https://your-host/api/v1/vehicles?limit=25"

POST /api/v1/vehicles — create a vehicle. Body: registration (required), make, model, year,class, fuelType, capacity.

Telematics ingest

POST /api/v1/telematics/ping — accepts a single GPS fix per request. Authenticate with either an API key (hardware tracker) or the session cookie (driver app). Body matches the TelematicsPing type plus a tenantId:

{
  "tenantId": "tnt_xxx",
  "vehicleId": "veh_xxx",
  "deviceId": "obd-2-1234",
  "ts": 1715000000000,
  "lat": -1.286389,
  "lng": 36.817223,
  "speedKph": 42,
  "headingDeg": 180,
  "ignition": true,
  "accuracyM": 8.5,
  "events": ["harsh_brake"]
}

The server writes to RTDB /tracking/{tenantId}/{vehicleId} (sub-second fan-out to live maps) and Firestore (denormalisedvehicles.lastPing plus down-sampled archive in telematicsPings).

Errors

• missing_authorization — 401, no Bearer header.
• invalid_api_key — 401, key not recognised.
• revoked_api_key — 401, key was revoked.
• tenant_inactive — 403, tenant is suspended / archived.
• rate_limit_exceeded — 429, slow down.
• invalid_body — 400, body failed Zod validation.