Upgrading - Upgrading to 1.2

There are no breaking changes in this update, however we are introducing a new authentication method. If you’re currently using createClient() with the authEndpoint option, we recommend you read on.

Liveblocks 1.2 provides new ways to specify who can access certain rooms, and with which permissions they can enter. Our new-style security tokens also bring speed improvements, allowing clients to connect Liveblocks rooms even quicker, as well as permitting authorization tokens that can be used for multiple rooms.

Public key authentication changes

With Liveblocks 1.2, entering rooms with your public key will be noticeably quicker. If you’re currently using Liveblocks public keys, no changes are required to your application.

Private key authentication changes

Upgrading your existing auth back end will opt you in to using our new-style auth tokens, which offer the following benefits:

• Grant users permission to multiple rooms in one transaction, meaning fewer requests on your back end.
• Much quicker to join rooms, particularly any after the first.
• Unlock access to upcoming features, such as Comments (currently in private beta).

If you’re currently using Liveblocks private keys, no changes are strictly necessary, but we do highly recommend you upgrade your application’s back end.

How to upgrade?

You can upgrade to 1.2 by downloading the latest version of each Liveblocks package you’re using, for example in a React app:

$npm install @liveblocks/client@latest @liveblocks/node@latest @liveblocks/react@latest

We’ll walk you through the necessary changes below, but first, if you currently have a Liveblocks application in production, we recommend following a rollout plan, to prevent any users running an old Liveblocks client, during the upgrade, from having issues.

Rollout plan

1. Keep your existing back end endpoint (e.g. /api/auth).

2. Create a new authentication endpoint for the upgrade (e.g. /api/liveblocks-auth).

3. In your front end, point createClient()’s authEndpoint URL to the new endpoint.

4. Done! You can deploy your application now.

5. Later, when all your application’s clients have been upgraded to the latest version, you can safely remove the old endpoint.

Deciding which token to use

In Liveblocks 1.2 there are two new ways to authenticate with @liveblocks/node.

• Access tokens are recommend for most applications.
• ID tokens are best if you’re using fine-grained permissions with our REST API.

Access tokens and ID tokens both allow for multiple room support, but have different sources of truth. The old authentication method, single-room tokens with authorize, is still supported but will eventually be deprecated.

Access tokens

Access tokens are the new recommended way to authenticate, because they’re easy to manage from your custom back end. They follow the analogy of a hotel key card. Anyone that has a key card can enter any room that the card gives access to. It’s easy to give out these key cards right from your back end.

Upgrading to access tokens

First, create a new endpoint in your back end, next to your existing /api/auth endpoint. We recommend going with /api/liveblocks-auth.

Let’s implement it to issue tokens that would be equivalent to your current single-room token based setup.

1. Create a client

   Create a Node.js client that allows you to interact with our REST API.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});

2. Start an auth session inside your endpoint

   Every session should have a unique user ID, which is typically the ID of the user in your database.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function POST(request) {  const user = { id: "olivier@example.com", info: { name: "Olivier" }};
     const session = liveblocks.prepareSession(    user.id,    { userInfo: user.info } // Optional  );}

3. Give the user access to the room

   Give if the current user access to the room, with either session.FULL_ACCESS, or session.READ_ACCESS.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function POST(request) {  const user = { id: "olivier@example.com", info: { name: "Olivier" }};
     const session = liveblocks.prepareSession(    user.id,    { userInfo: user.info } // Optional  );
     const { room } = await request.json();  session.allow(room, session.FULL_ACCESS);}

4. Authorize the user and return the result

   Give if the current user access to the room, with either session.FULL_ACCESS, or session.READ_ACCESS.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function POST(request) {  const user = { id: "olivier@example.com", info: { name: "Olivier" }};
     const session = liveblocks.prepareSession(    user.id,    { userInfo: user.info } // Optional  );
     const { room } = await request.json();  session.allow(room, session.FULL_ACCESS);
     const { status, body } = await session.authorize();  return new Response(body, { status });}

5. Point to the new endpoint

   In the front end of your app, update your liveblocks.config.ts file to connect to the new endpoint.

   liveblocks.config.ts

   import { createClient } from "@liveblocks/client";
   const client = createClient({  authEndpoint: "/api/liveblocks-auth",});

6. You’re migrated!

   You’ve successfully migrated, and now have a similar authentication set up as before! However, there are other new features we can take advantage of.

7. Bonus: Issue access to multiple rooms

   With Liveblocks 1.2, you can also issue access to multiple rooms, or even use a prefix-based wildcard in the room name, enabling any amount of rooms! You can learn more about this in our access token guide.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function POST(request) {  const user = { id: "olivier@example.com", info: { name: "Olivier" }};
     const session = liveblocks.prepareSession(    user.id,    { userInfo: user.info } // Optional  );
     const { room } = await request.json();  session.allow(room, session.FULL_ACCESS);  session.allow("my-room-*", session.READ_ACCESS);  session.allow("my-other-room", session.READ_ACCESS);
     const { status, body } = await session.authorize();  return new Response(body, { status });}

Learn more about access tokens

You can find guides for your specific framework and learn more about permissions in our access tokens authentication guides.

Here’s a full working example of access tokens in a Next.js endpoint.

ID tokens

Are you already using our REST API to assign fine-grained permissions to each room, via Create room or Update room APIs? If so, ID tokens may work best for you.

ID tokens follow the analogy of a membership card. Anyone with that membership card can try to enter a room, but your permissions will be checked at the door. This approach to permissions is most powerful because it can be set up very finely, but it comes at the cost of having to keep those permissions programmatically in sync with Liveblocks. We recommend it for advanced use cases only.

Upgrading to ID tokens

If you’ve already set up room permissions using our REST API, then this should be easy!

First, let’s create a new endpoint in your back end, next to your existing /api/auth endpoint. We recommend going with /api/liveblocks-auth.

All you have to do now is implement it as follows:

1. Create a client

   Create a Node.js client that allows you to interact with our REST API.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});

2. Identify the user and return the result

   Whichever userId (or groupIds) you pass will be used to check the permissions you configured in your Liveblocks account already.

   import { Liveblocks } from "@liveblocks/node";
   const liveblocks = new Liveblocks({  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",});
   export async function POST(request) {  const user = { id: "olivier@example.com", info: { name: "Olivier" }};
     const { status, body } = await liveblocks.identifyUser({    userId: user.id,    groupIds, // Optional  });
     return new Response(body, { status });}

3. Point to the new endpoint

   In the front end of your app, update your liveblocks.config.ts file to connect to the new endpoint.

   liveblocks.config.ts

   import { createClient } from "@liveblocks/client";
   const client = createClient({  authEndpoint: "/api/liveblocks-auth",});

4. You’re migrated!

   You’ve successfully migrated to id tokens!

5. Bonus: Use our REST API to handle permissions

   ID tokens use permissions set with our REST API. For example, this is how you create a room, and give a user full access.

   fetch("https://api.liveblocks.io/v2/rooms", {  method: "POST",  body: JSON.stringify({    id: "my-room-name",    defaultAccesses: [],    userAccesses: {      "olivier@example.com": ["room:write"]    }  }),});

Learn more about ID tokens

You can find guides for your specific framework and learn more about permissions in our ID tokens authentication guides.

Here’s a full working example of ID tokens in a Next.js endpoint.

If you have issues with these new patterns and need help, please let us know by email or by joining our Discord community! We’re here to help!