Skip to main content

Protocol Structure

Hivekit uses a simple, JSON-based message format. Each message consists of an array of actions, e.g.

typ: 'obj', // type == object
act: 'set', // action == set (quick way to UPSERT)
id: 'rider/SadeIbrahim', // object id
rea: 'lagos', // realm id
loc: { lon: 3.37590, lat: 6.51309 } // location
typ: 'obj',
act: 'set',
id: 'rider/AyofemiMusa',
rea: 'lagos',
loc: { lon: 3.37592, lat: 6.51317 }

The keys in Hivekit's messages are always abbreviated to three-letter codes to decrease overall message size. Client libraries then expand them into human-readable values. [You can find the full list of fields and shortcodes here.]

Request/Response & Correlation IDs

Hivekit messages can be sent in response to a request or can be sent by the server or other clients as an update. To map requests to responses, you can add a unique correlation id cid to your messages that will be returned as a response by the server.

// sent to the server
typ: 'obj',
act: 'cre',
id: 'object-a-oLO5Cmr5kRLIl_EinZ68H',
rea: 'realm-a-LZl82XWWycWStqokUjWez',
lab: 'Object A Label',
loc: { lon: 13.404954, lat: 52.520008 },
dat: { type: 'scooter', charge: 0.5 },
cid: 'LZuwP3tAeDaAYnbEapkOG' // this correlation id will help us map the server's response to this request

// received from the server
id: 'object-a-oLO5Cmr5kRLIl_EinZ68H', // id for the object
cid: 'LZuwP3tAeDaAYnbEapkOG', // correlation id for the request
res: 'suc' // result = success

Persistent Connections need to send an auth message first

There is one message in Hivekit that breaks the schema - and that's the initial authentication message.

[There are several non-message-based ways to authenticate your client with Hivekit, e.g. Cookies or Authorization headers.] But, if you choose to authenticate by sending your authentication token as a message, your first message must look like this:

Bearer TOKEN

The reason is that Hivekit will keep your connection initially in a "quarantine" state and won't even parse incoming messages until the authentication token is received. Here's how you would connect and authenticate a Websocket in NodeJS

import WebSocket from "ws"; // node only - in the browser, just use window.WebSocket
const ws = new WebSocket('wss://')
ws.on('open', () => {
ws.send('Bearer YOUR_API_TOKEN');
ws.on('message', msgBuffer => {
JSON.parse(msgBuffer.toString()).forEach(msg => {
if (msg.typ == 'sys' && msg.act == 'aut' && msg.res == 'suc') {
// hurray, we're connected and authenticated :-D