Go to liveblocks.iogo to documentation home

API Reference - @liveblocks/node

The two main things offered by @liveblocks/node:

  1. The authorize function, which helps you implement custom authentication in your backend.
  2. The WebhookHandler class, which helps you implement webhook handlers.

authorize

The purpose of authorize() is to help you implement your custom authentication backend, i.e. the blue "server" part of this diagram:

Auth diagram

If the current user has access to the provided room, call this function from your authorization endpoint and return the result as an HTTP response.

When calling the authorize function, you are telling (!) Liveblocks that the user you specify is authenticated, for which rooms, and which permissions they will have.

At the very least, you must pass a userId and a roomId. Optionally, userInfo can be used to add information about the current user that will not change during the session. This information will be accessible in the client to all other users in Room.getOthers. It can be helpful to implement avatars or display the user’s name without introducing a potential impersonification security issue.

  • userId cannot be longer than 128 characters.
  • userInfo cannot be longer than 1024 characters once serialized to JSON.

Example using Next.js

import { authorize } from "@liveblocks/node";
// Replace this key with your secret key provided at// https://liveblocks.io/dashboard/projects/{projectId}/apikeysconst secret = "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx";
export default async function auth(req, res) {  /**   * Implement your own security here.   *   * It's your responsibility to ensure that the caller of this endpoint   * is a valid user by validating the cookies or authentication headers   * and that it has access to the requested room.   */  const room = req.body.room;  const response = await authorize({    room,    secret,    // Corresponds to the UserMeta[id] type defined in liveblocks.config.ts    userId: "123",    groupIds: ["456"], // Optional    userInfo: {      // Optional, corresponds to the UserMeta[info] type defined in liveblocks.config.ts      name: "Ada Lovelace",      color: "red",    },  });  return res.status(response.status).end(response.body);}

Example using Express.js

const express = require("express");const { authorize } = require("@liveblocks/node");
// Replace this key with your secret key provided at// https://liveblocks.io/dashboard/projects/{projectId}/apikeysconst secret = "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx";
const app = express();
app.use(express.json());
app.post("/api/auth", (req, res) => {  /**   * Implement your own security here.   *   * It's your responsibility to ensure that the caller of this endpoint   * is a valid user by validating the cookies or authentication headers   * and that it has access to the requested room.   */  authorize({    room: req.body.room,    secret,    userId: "123",    userInfo: {      // Optional      name: "Ada Lovelace",      color: "red",    },  })    .then((authResponse) => {      res.send(authResponse.body);    })    .catch((er) => {      res.status(403).end();    });});

WebhookHandler

The WebhookHandler class is a helper to handle webhook requests from Liveblocks.

It’s initialized with a signing secret that you can find in your project’s webhook page.

const webhookHandler = new WebhookHandler(process.env.WEBHOOK_SECRET);

verifyRequest

Verifies the request and returns the event.

const event = webhookHandler.verifyRequest({  headers: req.headers,  rawBody: req.body,});

Example

import { WebhookHandler } from "@liveblocks/node";
// Will fail if not properly initialized with a secretconst webhookHandler = new WebhookHandler(process.env.WEBHOOK_SECRET);
export default function yourCustomWebhookRequestHandler(req, res) {  try {    const event = webhookHandler.verifyRequest({      headers: req.headers,      rawBody: req.body,    });
    // do things with the event of type `WebhookEvent`
    if (event.type === "storageUpdated") {      // do things with the event of type `StorageUpdatedEvent`    } else if (event.type === "userEntered") {      // do things with the event of type `UserEnteredEvent`    } else if (event.type === "userLeft") {      // do things with the event of type `UserLeftEvent`    }  } catch (error) {    console.error(error);    return res.status(400).end();  }
  res.status(200).end();}
Edit this page
Helpful?
System status
© 2023 Liveblocks Inc.