Skip to main content

Usage & Authentication

Hivekit comes with an easy to use HTTP API that allows you to create, read, update or delete realms, objects, areas and other Hivekit entities. This makes it easy to integrate with Hivekit from languages that don't have a native Hivekit SDK. There are, however, some things the HTTP API can't do - specifically all realtime functionality like subscriptions or event streams. For these, use a Hivekit SDK or the Websocket/MQTT/TCP API directly.

API Structure​

The API is a classic REST API, meaning it uses clearly structured URLs, HTTP verbs and status codes. The base URL is https://api.hivekit.io/v2/. All endpoints are prefixed with this URL. For example, to create a new realm, you would send a POST request to https://api.hivekit.io/v2/realm/{realmId} with the realm data in the request body. Request bodies and replies are always JSON encoded - so make sure to set your content type to application/json for POST and PATCH requests.

Authentication​

All API endpoints require authentication using an API token. You can create tokens in the Token Section of the access management page.

There are three ways to get the token into an API request:

Pass the token as a query parameter​

You can pass the token as a query parameter in the URL. This is the easiest way to get started and is generally safe for production use as queryStrings are encrypted in SSL environments. The query parameter is called token. For example, to read an object with the token abc123, you would send a GET request to https://api.hivekit.io/v2/realm/{realmId}/object/{objectId}?token=abc123.

Pass the token as part of the payload​

You can also pass the token as part of the request body for POST and PATCH requests. Simply specify a token property.

import needle from 'needle';
const url = `https://api.hivekit.io/v2/realm/realm-123`;
const response = await needle('post', url, {
    label: 'My first realm',
    token: 'abc123'
}, { json: true });

Pass the token as a header​

The most secure way to pass the token is as a header. Simply add a Authorization: Bearer {token} header to your request.