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.
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.
Upgrading your existing auth back end will opt you in to using our new-style auth tokens, which offer the following benefits:
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.
You can upgrade to 1.2 by downloading the latest version of each Liveblocks package you’re using, for example in a React app:
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.
Later, when all your application’s clients have been upgraded to the latest version, you can safely remove the old endpoint.
In Liveblocks 1.2 there are two new ways to authenticate with
Access tokens and ID tokens both allow for multiple room support, but have
different sources of truth. The old authentication method, single-room tokens
authorize, is still supported but will eventually be deprecated.
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.
First, create a new endpoint in your back end, next to your existing
endpoint. We recommend going with
Let’s implement it to issue tokens that would be equivalent to your current single-room token based setup.
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.
Here’s a full working example of access tokens in a Next.js endpoint.
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.
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
All you have to do now is implement it as follows:
Here’s a full working example of ID tokens in a Next.js endpoint.