Gateway / V1
Gateway V1
Gateway V1 connections, subscriptions and supported updates.
Overview
Gateway V1 provides authenticated connections and subscriptions to supported vehicle telemetry updates. No delivery or latency guarantee is implied.
Unlike the REST API, which is request-response based, the Gateway API establishes a persistent bidirectional connection between the client and the Fleet Management Gateway. Once connected and authenticated, clients receive Real-time telemetry events as they occur without repeatedly polling the server.
The Gateway API is intended for applications that require live fleet monitoring, dashboards, dispatch systems, mobile applications, command centers, and other Real-time integrations.
The Gateway delivers the supported TLGPS vehicle-state model. Availability depends on the configured tracking source and device.
The Gateway API is intentionally lightweight. The gateway is responsible for authentication, authorization, subscription management, and Real-time event delivery. Clients are responsible for maintaining the connection and managing subscriptions.
Gateway URL
Configured public endpoint:
wss://ws.tlgps.athear.ly
Use the endpoint supplied for your environment. All vehicle identifiers and telemetry examples here are synthetic; credential values are placeholders.
Use wss:// for deployed integrations. Local development may use ws://; use the configured public endpoint.
Origin Policy
Browser connections send an HTTP Origin during the WebSocket upgrade. When an Origin is present, it must exactly match an allowed origin configured by the TLGPS operator. Coordinate browser-origin requirements with your TLGPS contact.
Non-browser integration clients commonly omit the Origin header. A missing Origin is permitted; it does not bypass token authentication or operation/resource authorization.
Protocol Version
Current version: V1
Future protocol versions may introduce additional event types or capabilities while preserving compatibility with existing clients whenever practical.
Authentication
All Gateway connections require authentication. Integration consumers use a Gateway-capable Personal Access Token. First-party Portal browsers use a short-lived, one-use Gateway ticket and must never embed a PAT in browser code.
Authentication occurs after the Gateway connection has been established.
Unlike the REST API, where a PAT is transmitted in the HTTP Authorization header with every request, the Gateway authenticates the socket once. The authenticated connection remains valid until it is closed or the server terminates it through heartbeat or bounded authorization checks.
Obtaining an Access Token
Before connecting as an integration client, obtain a token through an authorized TLGPS account. The active Company must have Gateway access enabled.
A user authorized to issue tokens can use the Portal API Tokens page. If that capability is unavailable, contact an authorized administrator; this documentation does not provision tokens.
Each Personal Access Token contains:
| Property | Description |
|---|---|
| Token | Secret token used to authenticate API requests and Gateway connections |
| Name | Human-readable name used to identify the token |
| Abilities | Permissions granted to the token |
| Expiration Date | Date and time after which the token becomes invalid |
Applications should securely store issued tokens. Tokens should never be embedded in client-side applications or exposed to end users.
Token Abilities
Each Personal Access Token is assigned one or more abilities.
Examples include:
telemetry.subscribefor Gateway subscriptions
REST abilities such as vehicles.view and vehicles.history apply to REST operations; they do not substitute for Gateway access.
The Gateway verifies that the authenticated token includes the required ability before allowing subscriptions.
For example, subscribing to Real-time telemetry requires the telemetry.subscribe ability.
If the required ability is missing, the subscription request is rejected.
The Sanctum ability is distinct from application authorization. The authenticated User must also retain the telemetry.subscribe Gateway permission and resource-level vehicle access.
Token Expiration
Personal Access Tokens may have an expiration date configured when they are created.
After expiration:
- New Gateway authentication attempts will fail.
- Existing authenticated connections are terminated after bounded authorization refresh detects expiration or revocation.
- Clients should obtain a new Personal Access Token before reconnecting.
Browser Gateway Tickets
The first-party Portal uses a separate short-lived browser credential. It is not a customer token-provisioning API. Do not embed a Personal Access Token in public browser code; use a trusted server-side integration. Coordinate any custom browser integration with TLGPS before implementation.
Authentication Flow
The Gateway authentication lifecycle consists of four stages.
Client Gateway
│ │
│ │
├──────────── Connect ─────────────►│
│ │
├──────── Authenticate ──────────-─►│
│ │
│◄──────── Authenticated ───────────│
Once authenticated, the connection may create one or more subscriptions and receive Real-time events until the connection is closed.
Authentication Message
The client authenticates by sending an authenticate message.
{ "type": "authenticate", "data": { "token": "<gateway-ticket-or-personal-access-token>" } }
Successful Authentication
If authentication succeeds, the gateway responds with:
{ "type": "authenticated", "timestamp": "2026-07-01T10:19:12+02:00", "data": { "gateway": { "version": "v1", "heartbeat": { "idle_timeout": 120 } } } }
gateway.heartbeat values are in seconds.
Authentication Failure
If authentication fails, the gateway responds with an error event.
{ "type": "error", "timestamp": "2026-06-30T19:38:34+02:00", "data": { "error": "authentication_failed", "message": "Authentication failed." } }
The gateway may immediately close the connection after sending the error.
Connection Closed
When the gateway closes the connection, it sends a final message describing the reason.
{ "type": "connection_closed", "timestamp": "2026-06-30T19:38:34+02:00", "data": { "reason": "unauthorized", "message": "Connection authorization is no longer valid." } }
Clients should treat this message as the final event before the socket is closed.
After a disconnection, subscriptions are not restored automatically. Clients must establish a new Gateway connection, authenticate again, and recreate any required subscriptions.
Authentication Notes
- Authentication is performed once per Gateway connection.
- Every connection must authenticate independently.
- PATs inherit the permissions of their owning User and require the
telemetry.subscribeability. - PATs may expire or be deleted/revoked at any time.
- Browser tickets are one-use credentials with a default 60-second TTL.
- A browser reconnect obtains a new ticket; a healthy socket does not renew tickets.
- The gateway does not accept unauthenticated subscription requests.
- An anonymous socket becomes eligible for closure after the configured authentication timeout (15 seconds by default) and is removed on the next maintenance sweep.
- The authenticated confirmation event contains the global session configuration payload (gateway). Integration clients should capture this metadata upon handshake to dynamically configure background heartbeat intervals and track API contract versioning.
Long-Lived Authorization
Access remains subject to the token owner's active Company, Gateway availability, effective permissions, token validity and current vehicle visibility. Access changes can remove subscriptions or close connections. Rechecks are periodic, not an instantaneous revocation guarantee. Clients must handle closure and re-authorize on reconnection.
Protocol
The Fleet Management Gateway API uses a message-based protocol built on top of a persistent Gateway connection.
Every message exchanged between the client and the gateway is encoded as a JSON object.
Each message represents a single protocol event, such as authentication, subscription management, heartbeat, or Real-time telemetry delivery.
Clients use TLGPS vehicle UUIDs rather than tracking-provider identifiers.
Message Envelope
Server messages use the following envelope. Client requests use their message-specific shapes below; a client timestamp is not required.
{ "type": "<message-type>", "timestamp": "", "data": {} }
| Field | Type | Description |
|---|---|---|
type |
string | Identifies the message type. |
timestamp |
datetime | Message timestamp in ISO-8601 format |
data |
object | Message payload. The structure depends on the message type. |
Using a consistent envelope allows clients to deserialize every message using the same logic before handling the specific event.
Client Messages
Client messages are sent from the application to the Fleet Management Gateway.
The current protocol supports the following message types.
| Type | Description |
|---|---|
authenticate |
Authenticates the Gateway connection. |
subscribe |
Creates a Real-time subscription. |
unsubscribe |
Removes an existing subscription. |
ping |
Verifies connection health. |
Additional client message types may be introduced in future protocol versions.
Server Messages
Server messages are sent by the Fleet Management Gateway to connected clients.
| Type | Description |
|---|---|
authenticated |
Authentication completed successfully. |
subscribed |
Subscription acknowledged. |
unsubscribed |
Subscription removed. |
telemetry |
Real-time vehicle telemetry event. |
pong |
Response to a client heartbeat. |
error |
Protocol or validation error. |
connection_closed |
Final message sent before the gateway closes the connection. |
Message Ordering
Messages generated for a single Gateway connection are delivered in the order they are produced by the gateway. Clients should not assume ordering across multiple gateway instances, separate connections, or reconnections.
Applications should always process each received event independently.
Unknown Messages
Clients should ignore message types they do not recognize.
This allows applications to remain compatible with future protocol versions that introduce new message types without breaking existing implementations.
Protocol Notes
- Every server response corresponds to a specific client operation or gateway event.
- Every protocol message uses the same JSON envelope.
- The
typefield identifies the message being exchanged. - The
datafield contains the message-specific payload. - Unknown message types should be ignored rather than treated as protocol errors.
- Clients should not rely on undocumented message fields.
Connection Lifecycle
Every Gateway client should implement the following lifecycle.
Client Gateway
│ │
│ │
├──────────── Connect ─────────────►│
│ │
├──────── Authenticate ──────────-─►│
│ │
│◄──────── Authenticated ───────────│
│ │
│------> Ping --------------------->│
│<--------------------- Pong -------│
│ │
│ (Maintain Connection) │
│ │
├────────── Subscribe ─────────────►│
│ │
│◄────────── Subscribed ────────────│
│ │
│◄────── Vehicle Telemetry ─────────│
│◄────── Vehicle Telemetry ─────────│
│◄────── Vehicle Telemetry ─────────│
Every client-initiated operation has a corresponding server acknowledgement.
Message Exchange Pattern
| Client | Server |
|---|---|
authenticate |
authenticated |
subscribe |
subscribed |
unsubscribe |
unsubscribed |
ping |
pong |
A successful Gateway client should always perform the following steps in order:
- Connect to the Fleet Management Gateway.
- Authenticate using a valid integration PAT or browser Gateway ticket.
- Maintain the connection by sending periodic
pingmessages and receivingpong. - Subscribe to one or more Real-time topics.
- Receive Real-time events until the connection is closed.
This sequence forms the foundation of the Fleet Management Real-time protocol.
Subscription requests sent before successful authentication are rejected.
Likewise, clients that fail to maintain an active connection may be disconnected by the gateway.
Heartbeat
Gateway connections are long-lived and may remain open for extended periods of time.
To verify that both the client and the gateway remain reachable, the Fleet Management Gateway implements a heartbeat mechanism.
Clients should periodically send a ping message.
The gateway responds with a corresponding pong message containing the current gateway timestamp.
Failure to maintain heartbeat traffic may result in the connection being closed by the gateway.
Heartbeat Interval
The Fleet Management Gateway continuously monitors authenticated connections.
Clients should periodically send ping messages throughout the lifetime of the connection.
If no heartbeat is received within the configured idle timeout, the gateway closes the connection.
The default configuration is:
| Setting | Default |
|---|---|
| Idle timeout | 120 seconds |
| Recommended ping interval | 30–60 seconds |
Applications should send heartbeat messages more frequently than the configured timeout.
Ping
Clients send a heartbeat request using the following message.
{ "type": "ping", "data": {} }
Pong
The gateway responds with:
{ "type": "pong", "timestamp": "2026-06-30T19:38:34+02:00", "data": {} }
The returned timestamp represents the Fleet Management server time.
Heartbeat Notes
- Heartbeats verify that both endpoints remain connected.
- Heartbeat messages do not require any subscription.
- Heartbeat messages contain no telemetry.
- Clients should continue sending heartbeat requests for the lifetime of the connection.
- The gateway may terminate idle or unresponsive connections.
Closing Connection
Close Reasons
| Reason | Description |
|---|---|
heartbeat_timeout |
Client stopped sending heartbeats |
duplicate_authentication |
Client attempted to authenticate an authenticated connection |
server_shutdown |
Gateway is shutting down |
maintenance |
Gateway is entering maintenance |
unauthorized |
Authentication timed out or bounded authorization is no longer valid |
protocol_violation |
Gateway closed the connection for a protocol violation |
Subscriptions
Subscriptions determine which Real-time events are delivered to a connected client.
After successful authentication, clients may subscribe to one or more topics. Each subscription instructs the Fleet Management Gateway to deliver events matching the specified resource.
A single Gateway connection may maintain multiple active subscriptions simultaneously.
Subscriptions remain active until one of the following occurs:
- The client explicitly unsubscribes.
- The Gateway connection is closed.
- The gateway disconnects the client.
Subscription Model
Every subscription consists of two components:
| Field | Description |
|---|---|
topic |
The type of resource being monitored. |
identifier |
The UUID identifying the specific resource. |
The current protocol supports subscriptions to specific vehicles only.
Subscription Lifecycle
Client Gateway │ │ ├────────── Subscribe ─────────────────►│ │ │ │◄───────── Subscribed ─────────────────│ │ │ │◄────────── Telemetry ─────────────────│ │◄────────── Telemetry ─────────────────│ │◄────────── Telemetry ─────────────────│ │ │ ├──────── Unsubscribe ─────────────────►│ │ │ │◄────────--------- Unsubscribed ───────│
Subscription Message
Clients create subscriptions by sending a subscribe message.
{ "type": "subscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
Subscription Fields
| Field | Type | Description |
|---|---|---|
topic |
string | Resource type to subscribe to. |
identifier |
UUID | UUID of the resource associated with the topic. |
Successful Subscription
When the subscription is accepted, the gateway responds with:
{ "type": "subscribed", "timestamp": "2026-07-05T15:37:10+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
Receiving a subscribed message indicates that the subscription has been successfully registered and the client will begin receiving matching Real-time events.
Removing a Subscription
Clients may stop receiving events by sending an unsubscribe message.
{ "type": "unsubscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
Successful Unsubscription
{ "type": "unsubscribed", "timestamp": "2026-07-05T15:37:10+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
Subscription Notes
- A client may maintain multiple active subscriptions simultaneously.
- One request may contain multiple vehicle subscriptions.
- Duplicate topic/identifier pairs produce one effective subscription.
- Batch preparation is all-or-nothing. If any requested vehicle is unavailable, none of that request is registered.
- Vehicle permission and current Company visibility constrain the subscription.
- Offline vehicles may be subscribed.
- A vehicle without resolved current state receives a
subscribedacknowledgment without an initialtelemetrymessage; future telemetry still reaches the active subscription. - Unsubscribing from a resource that is not currently subscribed has no effect.
- Subscriptions are scoped to the current Gateway connection.
- Closing the connection automatically removes all active subscriptions.
Available Topics
Topics define the type of Real-time resource a client wishes to monitor.
Each topic represents a logical stream of events within the Fleet Management System. Clients subscribe to a topic together with a resource identifier (UUID) to receive events related to that resource.
Only the vehicle topic is supported by this version. Other topic values are rejected.
Clients should ignore unknown message types to remain compatible with future protocol versions.
Currently Supported Topics
The current version of the Gateway API supports the following topic.
| Topic | Identifier | Description |
|---|---|---|
vehicle |
Vehicle UUID | Receives Real-time telemetry for a single vehicle. |
Vehicle Topic
The vehicle topic provides Real-time telemetry for a single vehicle.
Clients subscribe using the vehicle UUID.
The vehicle UUID is identical to the UUID exposed by the REST API.
Only telemetry matching the subscribed resource is delivered to the client.
The Vehicle topic is currently the only supported subscription topic. Additional topics may be introduced in future protocol versions while preserving the existing message format.
Required Permission
Integration PAT connections require both the telemetry.subscribe PAT ability and effective telemetry.subscribe application permission. First-party browser-ticket connections require structural Tracking availability plus effective tracking.live_map and effective vehicles.view; they do not additionally require telemetry.subscribe because the one-use ticket was issued specifically for the first-party Tracking capability.
Vehicle permission and current Company/vehicle visibility constrain every subscription batch.
Subscription
{ "type": "subscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
Subscription Acknowledgement
If the subscription is accepted, the gateway responds with a subscribed message.
{ "type": "subscribed", "timestamp": "2026-06-30T19:38:34+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
Receiving this message confirms that the subscription has been successfully registered and that Real-time events for the specified vehicle will begin streaming over the current Gateway connection.
Telemetry Event
Whenever new telemetry becomes available for the subscribed vehicle, the gateway sends a telemetry message.
{ "type": "telemetry", "timestamp": "2026-06-30T19:53:37+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" }, "vehicle": { "uuid": "01900000-0000-7000-8000-000000000001", "state": { "source": "realtime", "status": { "connection": "online", "movement": "parked" }, "coordinates": { "latitude": 0.0, "longitude": 0.0 }, "geo_address": null, "speed": { "kmh": 0, "mps": 0 }, "gps_status": true, "angle": 61, "altitude": -1, "ignition": { "status": "off" }, "oil": 0, "voltage": 26.16, "mileage": { "km": 27246189, "meters": 27246189000 }, "temperature": "-255", "timestamps": { "gps": "2026-06-30T17:52:51.000000Z", "received": "2026-06-30T17:52:52.506493Z", "last_synced": null } } } } }
The vehicle.state object uses the same shared scalar projection as REST Vehicle Location for an equivalent resolved snapshot: coordinate numbers, speed/distance units and rounding, status values, booleans and optional nulls. No device UUID, raw provider payload or credentials are included.
Gateway V1 state timestamps.gps, received and last_synced are UTC ISO-8601 strings with six fractional digits and Z, or null. REST V1 retains its existing application-timezone offset format at second precision. These compatibility formats describe the same underlying measurements; parse timestamps and compare at the available precision rather than comparing strings. The Gateway envelope's top-level timestamp is the message send time, in application-timezone ISO-8601 at second precision; it is not the GPS measurement time.
geo_address uses the address already available on the snapshot, or null; serialization performs no reverse-geocoding request. Both transports expose display_name, city, state, country and country_code. Gateway V1 additionally retains the existing nullable geocoder reference fields place_id, osm_type and osm_id for backward compatibility. REST deliberately omits them. Initial state and later updates use this same Gateway representation; initial telemetry is still conditional on a snapshot being available.
The message envelope remains transport-specific. Separate reads and subscriptions may observe different snapshots, so no byte-identical REST/Gateway payload or delivery/latency guarantee is implied.
Unsubscribe Request
Clients may stop receiving telemetry by sending an unsubscribe message.
{ "type": "unsubscribe", "subscriptions": [ { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } ] }
Unsubscription Acknowledgement
{ "type": "unsubscribed", "timestamp": "2026-06-30T19:55:12+02:00", "data": { "subscription": { "topic": "vehicle", "identifier": "01900000-0000-7000-8000-000000000001" } } }
After receiving this message, no further telemetry events for the specified vehicle will be delivered unless the client subscribes again.
Vehicle Topic Notes
- A client may subscribe to multiple vehicles simultaneously.
- Vehicle subscriptions may be submitted together in one array request.
- Vehicle UUIDs are identical to those used throughout the REST API.
- Every telemetry message contains the subscription that generated the event.
- The
vehiclepayload uses the same provider-independent tracking model as the REST API. - Telemetry is delivered only while the subscription remains active.
- Applications should tolerate receiving duplicate telemetry events.
Events
A successful subscription receives telemetry messages whenever new telemetry becomes available for the subscribed vehicle.
The gateway delivers only telemetry belonging to the requested vehicle.
Multiple vehicle subscriptions may exist simultaneously on the same Gateway connection.
Timestamps
| Timestamp | Meaning |
|---|---|
| message.timestamp | Time the gateway sent the Gateway message |
| vehicle.state.timestamps.gps | Time reported by the GPS device |
| vehicle.state.timestamps.received | Time the gateway received the telemetry |
| vehicle.state.timestamps.last_synced | Time the telemetry was synchronized into Fleet Management |
The message.timestamp property is generated by the Gateway and is present in every server message.
Error Messages
When a request cannot be processed, the gateway responds with an error message.
An error message does not necessarily terminate the Gateway connection. Depending on the error, the client may correct the request and continue using the existing connection.
Error Message
{ "type": "error", "timestamp": "2026-06-30T14:52:31+02:00", "data": { "error": "invalid_payload", "message": "Missing token." } }
Error Fields
| Field | Type | Description |
|---|---|---|
| error | string | Machine-readable error code |
| timestamp | Datetime | Error message timestamp in ISO-8601 format. |
| message | string | Human-readable error description |
Error Codes
| Error Code | Description |
|---|---|
| authentication_failed | Authentication failed because the supplied access token is invalid or expired. |
| already_authenticated | Client attempted to authenticate more than once. |
| unauthorized | The client must authenticate before sending this message. |
| forbidden | The authenticated client lacks the required permission. |
| invalid_json | The received message is not valid JSON. |
| invalid_payload | The message payload is malformed or missing required fields. |
| unknown_message | The specified message type is not supported. |
| invalid_subscription | The subscription resource identifier is invalid. |
| internal_error | An unexpected gateway error occurred. |
Additional error codes may be introduced in future protocol versions. Clients should treat unknown error codes as generic failures.
Unless otherwise specified, an
errormessage does not close the Gateway connection. Clients may correct the request and continue using the existing connection.
Appendix A — Message Reference
| Direction | Message | Description |
|---|---|---|
| → | authenticate | Authenticate the connection. |
| ← | authenticated | Connection authenticated. |
| → | ping | Keep the connection alive. |
| ← | pong | Heartbeat response. |
| → | subscribe | Subscribe to a topic. |
| ← | subscribed | Subscription acknowledged. |
| → | unsubscribe | Remove an active subscription. |
| ← | unsubscribed | Subscription removed. |
| ← | telemetry | Real-time telemetry event. |
| ← | error | Request could not be processed. |
| ← | connection_closed | Gateway is closing the connection. |
Compatibility
Clients should:
- Ignore unknown message types.
- Ignore unknown fields.
- Tolerate additional object properties.
- Treat unknown error codes as generic failures.
- Not rely on the order of object properties within JSON messages.
- Ignore additional message types introduced by newer protocol versions.
These guidelines allow clients to remain compatible with future protocol versions without requiring immediate updates.