AuthenticationSet up access token permissions with Next.js

Follow the following steps to start configure your authentication endpoint and start building your own security logic in Next.js’ /app directory.


  1. Install the liveblocks/node package

    $npm install @liveblocks/node
  2. Set up authentication endpoint

    Users need permission to interact with rooms, and you can permit access in an api/liveblocks-auth endpoint by creating the following app/api/liveblocks-auth/route.ts file. In here you can implement your security and define the rooms that your user can enter.

    With access tokens, you should always use a naming pattern for your room IDs, as this enables you to easily allow access to a range of rooms at once. In the code snippet below, we’re using a naming pattern and wildcard * to give the user access to every room in their organization, and every room in their group.

    import { Liveblocks } from "@liveblocks/node";
    const liveblocks = new Liveblocks({ secret: "",});
    export async function POST(request: Request) { // Get the current user from your database const user = (request);
    // Start an auth session inside your endpoint const session = liveblocks.prepareSession(, { userInfo: user.metadata } // Optional );
    // Use a naming pattern to allow access to rooms with wildcards // Giving the user read access on their org, and write access on their group session.allow(`${user.organization}:*`, session.READ_ACCESS); session.allow(`${user.organization}:${}:*`, session.FULL_ACCESS);
    // Authorize the user and return the result const { status, body } = await session.authorize(); return new Response(body, { status });}

    Read access token permission to learn more about naming rooms and granting permissions with wildcards. Note that if a naming pattern doesn’t work for every room in your application, you can grant access to individual rooms too.

  3. Set up the client

    On the front end, you can now replace the publicApiKey prop on LiveblocksProvider with authEndpoint pointing to the endpoint you just created.

    <LiveblocksProvider authEndpoint="/api/liveblocks-auth">

    If you need to pass custom headers or data to your endpoint, you can use authEndpoint as a callback instead.

  4. Attach metadata to users

    Optionally, you can attach static metadata to each user, which will be accessible in your app. First you need to define the types in your config file, under UserMeta["info"].

    declare global  interface Liveblocks {    UserMeta: {      id: string;
    // Example, use any JSON-compatible data in your metadata info: { name: string; avatar: string; colors: string[]; } }
    // Other type definitions // ... }}

    When authenticating, you can then pass the user’s metadata to prepareSession in the endpoint we’ve just created.

    // Get the current user from your databaseconst user = (request);
    // Start an auth session inside your endpointconst session = liveblocks.prepareSession(, { userInfo: { name:, avatar: user.avatarUrl, colors: user.colorArray, } });

    User metadata has now been set! You can access this information in your app through useSelf.

    export { useSelf } from "@liveblocks/react/suspense";
    function Component() { const { name, avatar, colors } = useSelf((me) =>;}

    Bear in mind that if you’re using the default Comments components, you must specify a name and avatar in userInfo.

More information

Both userId and userInfo can then be used in your React application as such:

const self = useSelf();console.log(;console.log(;
Auth diagram