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.
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:
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
Keep your existing back end endpoint (e.g.
/api/auth
).Create a new authentication endpoint for the upgrade (e.g.
/api/liveblocks-auth
).In your front end, point
createClient()
’sauthEndpoint
URL to the new endpoint.- Done! You can deploy your application now.
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.
Create a client
Create a Node.js client that allows you to interact with our REST API.
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.
Give the user access to the room
Give if the current user access to the room, with either
session.FULL_ACCESS
, orsession.READ_ACCESS
.Authorize the user and return the result
Give if the current user access to the room, with either
session.FULL_ACCESS
, orsession.READ_ACCESS
.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.tsYou’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.
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.
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:
Create a client
Create a Node.js client that allows you to interact with our REST API.
Identify the user and return the result
Whichever
userId
(orgroupIds
) you pass will be used to check the permissions you configured in your Liveblocks account already.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.tsYou’re migrated!
You’ve successfully migrated to id tokens!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.
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!