One auth model across native transports.

HTTP, WebSocket, and Cap'n Proto share the same authentication configuration. The server speaks plain HTTP/WebSocket/TCP, so production deployments should terminate TLS upstream.

Transports

HTTP/JSON

Primary command and query surface for native deployments. The server exposes generated OpenAPI and supports request body limits, timeouts, CORS, metrics, and auth middleware.

WebSocket

Subscription transport for live geofence events. Clients authenticate with the same auth model and subscribe to channels with collection-scoped subscription permissions.

Cap'n Proto

Async RPC transport for command/query flows and native replication. Enable it with capnp_enabled and expose capnp_listen_addr when RPC or followers need network access.

Authentication modes

Static bearer token for local development or trusted service flows.
HMAC JWT verification with jwt_secret.
PEM-configured asymmetric JWT verification with jwt_public_key_pem.
JWKS-configured asymmetric JWT verification with jwks_url.

Exactly one JWT verification source may be configured. For production, prefer JWT or JWKS, set require_auth = true, and disable the static bearer token.

JWT claim shape

{
  "sub": "user-123",
  "iss": "https://id.example.com",
  "aud": "latlng",
  "exp": 4102444800,
  "latlng_permissions": [
    {
      "collections": ["fleet-eu"],
      "actions": ["collections:list", "objects:read", "queries:read"]
    }
  ]
}

Authorization actions

Name	Description
`collections:list`	List collections visible to the principal. The /collections response is filtered by this permission.
`collections:create`	Create new collections in the instance.
`collections:delete`	Delete collections and their stored objects.
`collections:inspect`	Read collection metadata and inspection endpoints.
`objects:read`	Fetch objects and object data from permitted collections.
`objects:write`	Create, replace, or update objects in permitted collections.
`objects:delete`	Remove objects from permitted collections.
`queries:read`	Run spatial and text query routes. This is separate from live subscriptions.
`subscriptions:read`	Subscribe to live collection events over WebSocket subscribe and psubscribe flows.
`hooks:manage`	Create, list, update, and delete webhook hooks. List responses are filtered to manageable resources.
`channels:manage`	Create, list, update, and delete event channels. List responses are filtered to manageable resources.
`metrics:read`	Read the Prometheus metrics endpoint without granting broader admin access.
`admin:*`	Use operational and administrative routes.

Error responses

Every HTTP error has a JSON body of the form {"error": "…"}. Request bodies reject unknown fields, so a misspelt key fails with 400 instead of being ignored.

Status	Meaning
`400`	Invalid request: malformed JSON, unknown request fields, invalid geometry, out-of-range coordinates, non-positive radius, inverted bounds, invalid regex or expression, JSON-path edits on non-GeoJSON objects, or read-only mode.
`401 / 403`	Missing or insufficient credentials.
`404`	The collection, object, hook, channel, or route does not exist, including GET of a missing object.
`405`	The route exists but not for this HTTP method.
`415`	A request body was sent without content-type: application/json.
`500`	Storage or internal failure.

Other transports

HTTP/1.1 400 Bad Request
content-type: application/json

{"error":"bad request: invalid coordinates: latitude 999 is outside [-90, 90]"}

WebSocket error frames carry a machine-readable code next to error, for example bad_request, unauthorized, or forbidden.
Cap'n Proto responses carry an ErrorCode: none, notFound, badRequest, readOnly, internal, unauthorized, forbidden, or unavailable.
The TypeScript SDK raises BadRequestError for 400 and NotFoundError for 404, both subclasses of HttpError.

Frequently asked questions

Which authentication methods does latlng support?

latlng supports four authentication modes: a static bearer token for local or trusted service flows, HMAC JWT verification via jwt_secret, PEM-configured asymmetric JWT verification via jwt_public_key_pem, and JWKS-configured asymmetric JWT verification via jwks_url. Exactly one JWT verification source may be configured at a time.

Do HTTP, WebSocket, and Cap'n Proto share the same auth model?

Yes. All three transports use the same authentication configuration. The server speaks plain HTTP, WebSocket, and TCP; production deployments should terminate TLS upstream (for example via a reverse proxy).

How are permissions scoped?

Permissions are claims-based and scoped per collection. A JWT can carry latlng_permissions entries where each entry pairs a list of collections with a list of actions such as collections:list, objects:read, queries:read, or subscriptions:read.

← Configuration Next: Hooks →