Skip to main content

Authentication

Every connection to Hivekit's APIs, whether via HTTP Request or Websocket, needs to be authenticated. This happens by passing an authentication token in JWT format when you establish the connections.

How do I get an authentication token?​

There are two options:

  • You can create static tokens via the access management page. This is a great way to create long term API keys for use with backend services - or to authenticate your development environments.
  • You can create secrets via access management page and use them to sign your own tokens. This allows you to securely integrate Hivekit with your own user management system.

How do I use the token?​

The most common way is to pass the token to the Hivekit Client SDK you're using. E.g. for JavaScript:

import HivekitClient from "@hivekit/client-js";

const client = new HivekitClient();
await client.connect('wss://api.hivekit.io/v1/ws');
await client.authenticate('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtEY19JZTQxYUtUWWk0cmo3Vk1CNSJ9.eyJzdWIiOiJzZXJ2aWNlIiwidG5kIjoidXViSUlGd24tVldQcXlkOXJwWFdMIiwiaWF0IjoxNjgzNTcwNTU2LCJleHAiOjMzNjcxNDE3MDgsImlzcyI6InBsYXRmb3JtLmhpdmVraXQuaW8iLCJqdGkiOiJSZUQ3TlVXNHA0YzZiYnZCTmJUR3AifQ.Zq1stkIqIx3EBFLNCbs7semTn7qYyb6YK9h28lK1Xvc');

But there are also other ways to pass the token to the Hivekit API:

Both HTTP and Websocket requests can contain the token as a cookie header. The key for the cookie can be defined in conf.yml as authCookieName.

As Authorization: Bearer <token> header​

HTTP requests can include the token as a Bearer Auth header. Theoretically, Websockets could do the same in their initial connection request. However, the Websocket implementation in browsers does not allow setting headers directly. But if you connect to Hivekit from a server via Websocket, this option is open to you.

As an auth message sent via a persistent connection​

When connecting to the server via a persistent connection such as Websocket or TCP, the connection is initially kept in a state of "quarantine" and incoming messages are ignored. Only once a valid authentication message is sent will the connection be promoted to "trusted" and its messages processed. You can learn more about auth messages here.

What other information can I put into the JWT?​

Your JWT can also contain permissions to specify what your user can do and data provider patterns to specify which object this connection provides updates for.