The fleet & telematics data plane for your integration.

From credentials to first call in four steps.

Every endpoint requires an OAuth2 client-credentials bearer token carrying the scopes it needs. There is no user login: this is a server-to-server integration.

curl -X POST https://identity.haloniq.com/connect/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope="thirdparty.api.fleets_read thirdparty.api.vehicles_read"

curl https://developer.haloniq.com/v1/fleets \
  -H "Authorization: Bearer $ACCESS_TOKEN"

One scope per resource and action.

Requests are authorized by OAuth2 scopes. Read and write are granted separately, and device commands are split so wake-up can be allowed without reboot. A missing scope returns 403.

What the API exposes.

A versioned surface over the platform's fleet and telematics data plane, all under /v1.

Push, not poll: CloudEvents delivered to your endpoint.

Subscribe once and the platform POSTs a application/cloudevents+json envelope to your endpoint whenever something happens on your fleet. Every message follows the CloudEvents 1.0 specification, so the envelope is identical across all topic types. Only the data payload changes with the event type.

The CloudEvents envelope

Topic types & payloads

Five outbound topic types. The CloudEvents type discriminates the schema. Payload property names are camelCase, unlike the snake_case REST API.

Delivery transports

The delivery plane fans each event out to the subscriber's chosen transport. Through the Developer API today you subscribe over HTTPS callback; the Event Hub and Kafka transports are platform capabilities provisioned out-of-band (roadmap for self-serve).

Delivery headers & retries

Optional per-destination custom headers exist at the delivery-worker level but are not settable through the Developer API today.

Subscribing with the webhook-config API

Manage your subscription under /v1/organizations/{organizationId}/webhook-config. Reads require thirdparty.api.webhooks_read; every mutation requires thirdparty.api.webhooks_write. Optimistic concurrency uses ETag / If-Match (stale → 412); secrets are never returned by GET (only an auth_key_hint).

# register an HTTPS callback for closed journeys
curl -X PUT https://developer.haloniq.com/v1/organizations/$ORG_ID/webhook-config/topics/journeys \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"journeys","is_enabled":true,"delivery":{"url":"https://your-app.example.com/hooks/haloniq"}}'

Callback URLs must be absolute HTTPS, ≤2048 chars, and not loopback, link-local or private ranges (an SSRF guard blocks localhost, 127.0.0.0/8, 10/8, 172.16/12, 192.168/16, 169.254/16, ::1). Violations return 422 webhook.ssrf_blocked.

Generate a typed client from the OpenAPI 3.1 document.

The API publishes a machine-readable OpenAPI 3.1 document at /openapi/v1.json. Point a generator at it and get a fully typed client with no hand-written HTTP. Two generators are supported: Microsoft Kiota (the partner-SDK generator, multi-language) and NSwag (a dependency-light single-file C# client).

Microsoft Kiota: multi-language typed client

Kiota emits a request-builder tree (client.V1.Fleets[id].GetAsync()) and generates for C#, Java, Go, Python, TypeScript, PHP and Ruby from the same spec. OpenAPI 3.1 is detected natively, so no flag is needed.

# freeze the OpenAPI 3.1 document as the generation input
curl -fsSL https://developer.haloniq.com/openapi/v1.json -o v1.json

# one-time: install the generator
dotnet tool install --global Microsoft.OpenApi.Kiota

# generate the typed C# client (multi-file, request-builder tree)
kiota generate \
  -l CSharp \
  -d v1.json \
  -o ./sdk/kiota \
  -n Haloniq.DeveloperApi.Client \
  -c DeveloperApiClient \
  --clean-output

NSwag: single-file C# client

NSwag emits one .cs file with flat methods (client.GetFleetAsync(id)). Pin a 3.1-capable 14.x build, because 13.x mishandles the 3.1 type-arrays.

# one-time: install a 3.1-capable build (pin 14.7.1)
dotnet tool install --global NSwag.ConsoleCore --version 14.7.1

# emit a single-file C# client
nswag openapi2csclient \
  /input:v1.json \
  /classname:DeveloperApiClient \
  /namespace:Haloniq.DeveloperApi.Client \
  /output:DeveloperApiClient.cs

Which to choose

Reference output

A reference C# SDK, the frozen spec and the regeneration scripts are kept in this repository under .workspace/developer-api-handoff/sdk/, in the recommended layout:

sdk/
├── openapi/v1.json                 # frozen OpenAPI 3.1 doc = generation input
├── kiota/                          # Kiota multi-file client (Haloniq.DeveloperApi.Client)
│   ├── kiota-lock.json             # enables `kiota update` re-generation
│   └── Haloniq.DeveloperApi.Client.csproj
└── nswag/
    └── DeveloperApiClient.cs       # single-file NSwag client

Re-generate after a spec change with kiota update (it reads kiota-lock.json) or by re-running the NSwag command above.