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?​

For people using the Hivekit app, tenant administrators can enable email verification codes, password login and managed SSO identities under Settings → People. After local sign-in, the server issues a JWT through auth/session/. See Signing in & Passwords, Authentication Settings and the Authentication API.

For services and integrations, the existing token options remain available:

  • 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.

Local email/password authentication instead uses the HttpOnly hkt_session cookie to retrieve a session JWT. This cookie holds a session secret, not a JWT. Browser clients must include credentials when calling the authentication endpoints; see the Authentication API.

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.

Managed people and access​

People & Roles separates the tenant-wide people directory from platform access. Operational roles do not grant application permissions. Administrators set permissions, login methods and tenant-administrator rights independently for each person.

Local session JWTs have an explicit expiry and session reference. Logout, password changes/resets and access changes invalidate those sessions. Managed SSO providers bind existing external tokens to people and access policy; signing keys and browser redirects remain deployment settings. See People & Authentication Deployment for configuration and upgrades.