Skip to content
TLGPSDocumentation

Developer documentation

Gateway / V1

Authentication

Gateway V1 connections, subscriptions and supported updates.

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.subscribe for 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.subscribe ability.
  • 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.


Public documentation · authorized integration access required

Engineering-maintained documentation. Examples use synthetic data and placeholder credentials.

Back to top