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://auth.tst.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://app-haloniq-developerapi-tst-weu.azurewebsites.net/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).

# 1. Create the whole configuration (omit If-Match only on first creation)
curl -X PUT https://app-haloniq-developerapi-tst-weu.azurewebsites.net/v1/organizations/$ORG_ID/webhook-config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled":false,"topics":[{"type":"journeys","is_enabled":true,"delivery":{"url":"https://your-app.example.com/hooks/haloniq"}}]}'

# 2. Generate and capture the delivery key now; GET will never return it
AUTH_KEY=$(curl -fsS -X POST \
  https://app-haloniq-developerapi-tst-weu.azurewebsites.net/v1/organizations/$ORG_ID/webhook-config/regenerate-auth-key \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq -er '.auth_key')
printf 'Store this webhook key in your secret manager now:\n%s\n' "$AUTH_KEY"

# 3. Read the current ETag after key rotation
ETAG=$(curl -fsS -D - -o /dev/null \
  https://app-haloniq-developerapi-tst-weu.azurewebsites.net/v1/organizations/$ORG_ID/webhook-config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | sed -n 's/^[Ee][Tt][Aa][Gg]:[[:space:]]*//p' | tr -d '\r')

# 4. Enable delivery only after your receiver accepts the stored key
curl -X PATCH https://app-haloniq-developerapi-tst-weu.azurewebsites.net/v1/organizations/$ORG_ID/webhook-config \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{"is_enabled":true}'

The raw auth key is unrecoverable. Move $AUTH_KEY into your secret manager immediately, never commit or log it, and then unset AUTH_KEY. Every later GET returns only auth_key_hint; losing the raw value requires another key rotation.

After every successful mutation, read the configuration again and use its new ETag for the next conditional write.

At write time, callback URLs must be absolute HTTPS, ≤2048 chars. Literal hosts in loopback, link-local, IPv4 private, IPv6 unique-local and IPv4-mapped blocked ranges return 422 webhook.ssrf_blocked. Hostnames are not DNS-resolved during this write-time check, so a hostname that later resolves to a private address can still be saved. At delivery time the dispatcher independently resolves and pins an approved public destination IP; unsafe DNS answers or rebinding fail closed and no callback is sent.

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://app-haloniq-developerapi-tst-weu.azurewebsites.net/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 HaloniqApiClient \
  --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:HaloniqApiClient \
  /namespace:Haloniq.DeveloperApi.Client \
  /output:HaloniqApiClient.cs

Which to choose

Live generation input

Use the deployed OpenAPI 3.1 document as the source of truth. Freeze that document in your own release pipeline, commit the generated client in your integration repository, and regenerate it after a spec change with kiota update or by re-running the NSwag command above.