Skip to main content

Reseller & White-Label Platform API

Vehk provides a reseller/white-label platform architecture for reseller partners who build their own fleet management applications and resell Vehk-powered hardware, telemetry, and predictive maintenance services to downstream sub-clients (e.g. Client Alpha Logistics, Client Beta Express).

With the Reseller Platform API, partners can manage downstream sub-clients, provision devices, register vehicles, and query sub-client specific data completely programmatically through our external API without accessing the Vehk administrative portal.

Key Capabilities​

  1. Sub-Client Lifecycle Management: Programmatically create, inspect, update, and deactivate downstream client accounts (sub_clients).
  2. External Device Provisioning: Register devices, assign them to sub-clients, and generate secure MQTT telemetry credentials via API key.
  3. External Vehicle Registration: Upsert and link vehicles to sub-client fleets.
  4. Data Isolation & Filtering: Query devices, live telemetry locations, vehicles, and ML predictions filtered by sub_client_id.
  5. Usage Metering: Automated usage tracking per sub-client for reseller billing breakdowns.

Authentication & Permission Scopes​

All Reseller API endpoints require an external API key passed in the X-API-Key header:

X-API-Key: vehk_live_abcdef1234567890...

Required Permission Scopes​

To use Reseller features, ensure your API key has the following scopes assigned:

ScopeDescription
sub_clients:readList and inspect sub-client details and fleet counts
sub_clients:manageCreate, update, and deactivate sub-clients
devices:writeRegister, update, and decommission devices via external API
vehicles:writeRegister and update vehicles via external API
devices:readList devices and live locations (supports sub_client_id filter)
vehicles:readList vehicles (supports sub_client_id filter)
predictQuery maintenance predictions (supports sub_client_id filter)

Sub-Client Management (/api/external/sub-clients)​

1. Create a Sub-Client​

Create a downstream client organization. If sub_client_id is omitted, a URL-safe slug is automatically generated from name.

POST /api/external/sub-clients
Content-Type: application/json
X-API-Key: vehk_live_your_key

Request Payload:

{
  "name": "Client Alpha Logistics",
  "sub_client_id": "client-alpha",
  "contact_email": "ops@client-alpha.example",
  "contact_phone": "+91-9800000000",
  "metadata": {
    "tier": "enterprise_fleet",
    "region": "south_asia"
  }
}

Response (200 OK):

{
  "success": true,
  "sub_client": {
    "sub_client_id": "client-alpha",
    "name": "Client Alpha Logistics",
    "contact_email": "ops@client-alpha.example",
    "contact_phone": "+91-9800000000",
    "status": "active",
    "device_count": 0,
    "vehicle_count": 0,
    "created_at": "2026-08-24T14:00:00.000Z"
  }
}

2. List Sub-Clients​

Retrieve all sub-clients registered under your reseller account.

GET /api/external/sub-clients?status=active
X-API-Key: vehk_live_your_key

Response (200 OK):

{
  "total": 1,
  "sub_clients": [
    {
      "sub_client_id": "client-alpha",
      "name": "Client Alpha Logistics",
      "contact_email": "ops@client-alpha.example",
      "contact_phone": "+91-9800000000",
      "status": "active",
      "device_count": 12,
      "vehicle_count": 10,
      "created_at": "2026-08-24T14:00:00.000Z"
    }
  ]
}

3. Get Sub-Client Details​

GET /api/external/sub-clients/client-alpha

4. Update Sub-Client​

PUT /api/external/sub-clients/client-alpha
Content-Type: application/json

{
  "name": "Client Alpha Supply Chain",
  "status": "active"
}

5. Deactivate Sub-Client​

DELETE /api/external/sub-clients/client-alpha

Deactivating a sub-client soft-deactivates the record and unassigns devices linked to it.

Device Provisioning (/api/external/devices)​

Provision hardware devices, assign them to sub-clients, and auto-generate MQTT broker credentials.

1. Register a Device​

POST /api/external/devices
Content-Type: application/json
X-API-Key: vehk_live_your_key

Request Payload:

{
  "name": "Truck 01 Tracker",
  "imei": "860000000000001",
  "device_type": "obd_dongle",
  "sim_number": "+919800000000",
  "connection_method": "mqtt",
  "sub_client_id": "client-alpha",
  "vehicle": {
    "mode": "create",
    "make": "Tata",
    "model": "Prima 5530.S",
    "year": 2024,
    "license_plate": "KA-01-EQ-9901"
  }
}

Response (200 OK):

{
  "success": true,
  "device_id": "dev-4f8a91b2c3d4",
  "status": "active",
  "mqtt_broker": "mqtt.vehk.in:8883",
  "mqtt_username": "reseller-tech/dev-4f8a91b2c3d4",
  "mqtt_password_hash": "c8f1a23b4e5d6f7a8b9c0d1e2f3a4b5c",
  "mqtt_topic": "vehk/reseller-tech/devices/dev-4f8a91b2c3d4/telemetry",
  "vehicle_id": "VH-TATA-9901",
  "sub_client_id": "client-alpha"
}

Update or Reassign Device​

PUT /api/external/devices/dev-4f8a91b2c3d4
Content-Type: application/json
X-API-Key: vehk_live_your_key

{
  "sub_client_id": "client-beta"
}

Decommission Device​

POST /api/external/devices/dev-4f8a91b2c3d4/decommission
X-API-Key: vehk_live_your_key

Vehicle Registration (/api/external/vehicles)​

Register or update vehicles for downstream sub-clients.

POST /api/external/vehicles
Content-Type: application/json
X-API-Key: vehk_live_your_key

Request Payload:

{
  "make": "Eicher",
  "model": "Pro 3019",
  "year": 2024,
  "vin": "MC2E3KDC100123456",
  "license_plate": "KA01MJ9999",
  "sub_client_id": "client-alpha",
  "device_id": "dev-4f8a91b2c3d4"
}

Querying Sub-Client Data​

All major data retrieval endpoints accept an optional sub_client_id query parameter.

List Devices by Sub-Client​

GET /api/external/devices?sub_client_id=client-alpha

Get Sub-Client Live Telemetry Locations​

GET /api/external/devices/locations?sub_client_id=client-alpha

List Vehicles by Sub-Client​

GET /api/external/vehicles?sub_client_id=client-alpha

Query Maintenance Predictions by Sub-Client​

GET /api/external/predictions?sub_client_id=client-alpha

Telemetry Ingestion with sub_client_id​

When sending telemetry via POST /api/external/telemetry or POST /api/external/track, you can pass sub_client_id directly in the payload:

{
  "device_id": "dev-4f8a91b2c3d4",
  "sub_client_id": "client-alpha",
  "lat": 19.0760,
  "lon": 72.8777,
  "speed": 55.4,
  "coolant_temp": 88
}

If sub_client_id is omitted in the telemetry payload, Vehk automatically resolves and inherits the sub_client_id associated with the registered device.

Airtel M2M SIM Allocation & Billing​

Vehk integrates directly with the Airtel IoT Control Center (CMP API) to manage M2M SIM card provisioning and connectivity billing for reseller accounts:

  • SIM Allocation: Airtel M2M SIM cards assigned to reseller accounts are linked to configured devices and sub-clients.
  • Sim Billing & Invoicing: Reseller accounts can inspect live data usage (data_usage_mb), monitor active/suspended SIM states, sync with Airtel CMP via POST /api/sim-billing/sync, and view/pay monthly connectivity invoices via Razorpay integration (/api/sim-billing/invoices).
  • Dashboard Visibility: Full SIM inventory, connectivity status, and lifecycle control (Activate, Suspend, Safe Custody) are visible directly in the dashboard under Airtel IoT SIMs (/billing/sims).