With Liveblocks 1.2, we’re introducing new flexible authentication methods to
handle permissions for your collaborative application. Not only do these new
authentication methods improve loading performance significantly, they also make
it much easier to integrate Liveblocks into existing permission systems without
having to synchronize Liveblocks rooms every time permissions are updated.

- [Authenticating with public key](#public-key)
- [Authenticating with secret key](#secret-key)
- [Performance improvements](#performance-improvements)

## Authenticating with public key [#public-key]

```ts
const client = createClient({
  publicApiKey: "pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});
```

No changes are required if you’re currently using Liveblocks public keys, but
you’ll notice a significant performance improvement when connecting to
collaborative rooms. We’ll share more on this
[below](#performance-improvements).

## Authenticating with secret key [#secret-key]

```ts
import { createClient } from "@liveblocks/client";

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

We’re introducing two new ways to handle permissions with secret keys:

- [Access token](#access-token-permissions) are simple to use, and are
  recommended for most applications.
- [ID token](#id-token-permissions) are best if you’re using fine-grained
  permissions with our REST API.

<Slideshow
  slides={[
    {
      width: 820,
      height: 412,
      imageUrl: "/images/blog/whats-new-in-v1-2/access-token.png",
      caption: "Access",
    },
    {
      width: 820,
      height: 412,
      imageUrl: "/images/blog/whats-new-in-v1-2/id-token.png",
      caption: "ID token",
    },
  ]}
/>

### Access token permissions [#access-token-permissions]

Access tokens contain embedded permissions and metadata about the current user.
If you already have your own permission system, we recommend this approach as it
will allow you to set specific access to multiple rooms from one spot—without
having to synchronize permissions with Liveblocks.

<Figure highlight={false}>
  <Image
    src="/images/blog/whats-new-in-v1-2/access-token-diagram.png"
    alt="Access token diagram"
    width={820}
    height={576}
    quality={90}
  />
</Figure>

Here is what a standard Liveblocks authentication endpoint leveraging the access
token approach would look like in a Next.js application:

```ts file="app/api/liveblocks-auth/route.ts"
import { Liveblocks } from "@liveblocks/node";

// Create a client
const liveblocks = new Liveblocks({
  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});

export async function POST(request: Request) {
  const user = __getUserFromDB__(request);

  // Start an auth session inside your endpoint
  const session = liveblocks.prepareSession(
    user.id,
    { userInfo: user.metadata } // Optional
  );

  // Give the user access to the room
  const { room } = await request.json();
  if (room && __shouldUserHaveAccess__(user, room)) {
    // e.g. session.allow("my-room", ["room:write"])
    session.allow(room, session.FULL_ACCESS);
  }

  // Authorize the user and return the result
  const { status, body } = await session.authorize();
  return new Response(body, { status });
}
```

And what’s powerful about this approach is that you can allow access up to
multiple rooms at once within a given `session`.

```ts
session.allow("my-room-1", session.FULL_ACCESS);
session.allow("my-room-2", session.FULL_ACCESS);
session.allow("someone-elses-room-1", session.READ_ACCESS);

// Prefix-based wildcard patterns are supported as well,
// enabling you to give access to all rooms starting with a specific name
session.allow("my-room-*", session.FULL_ACCESS);
```

Make sure to check out the
[authentication step-by-step docs](/docs/rooms/authentication/access-token-permissions)
to set it up for your application.

### ID token permissions [#id-token-permissions]

ID tokens act as a verified ID representation of a user. With this approach,
permissions must be set at the room level so that ID tokens can be checked upon
entry, making sure the given user has access to the room. The Liveblocks servers
perform this authorization, so your permissions need to be set up front using
the Liveblocks REST API.

<Figure highlight={false}>
  <Image
    src="/images/blog/whats-new-in-v1-2/id-token-diagram.png"
    alt="ID token diagram"
    width={820}
    height={576}
    quality={90}
  />
</Figure>

Here’s an example of a Liveblocks authentication endpoint in Next.js which
implements the ID token approach:

```ts file="app/api/liveblocks-auth/route.ts"
import { Liveblocks } from "@liveblocks/node";

// Create a client
const liveblocks = new Liveblocks({
  secret: "sk_prod_xxxxxxxxxxxxxxxxxxxxxxxx",
});

export async function POST(request: Request) {
  const user = __getUserFromDB__(request);

  // Identify the user and return the result
  const { status, body } = await liveblocks.identifyUser({
    userId: user.id,
    groupIds, // Optional
  });

  return new Response(body, { status });
}
```

Make sure to check out the
[authentication step-by-step docs](/docs/rooms/authentication/id-token-permissions)
to set it up for your application.

## Performance improvements [#performance-improvements]

The new authentication model makes connecting to a Liveblocks room quicker due
to reduced round trips between clients and servers, enabling users to save
seconds of loading time.

### Public key performance improvements

JWT tokens are no longer generated when using public keys. This enables us to
save one round trip between Liveblocks servers and your client code.

<Slideshow
  slides={[
    {
      width: 820,
      height: 452,
      imageUrl: "/images/blog/whats-new-in-v1-2/public-roundtrips-before.png",
      caption: "Public key roundtrips before",
    },
    {
      width: 820,
      height: 452,
      imageUrl: "/images/blog/whats-new-in-v1-2/public-roundtrips-after.png",
      caption: "Public key roundtrips after",
    },
  ]}
/>

### Secret key performance improvements

JWT tokens are only generated once when using secret keys. This makes subsequent
connections to rooms significantly faster.

<Slideshow
  slides={[
    {
      width: 820,
      height: 502,
      imageUrl: "/images/blog/whats-new-in-v1-2/secret-roundtrips-before.png",
      caption: "Secret key roundtrips before",
    },
    {
      width: 820,
      height: 502,
      imageUrl:
        "/images/blog/whats-new-in-v1-2/secret-roundtrips-after-first.png",
      caption: "Secret key roundtrips after for first connection",
    },
    {
      width: 820,
      height: 502,
      imageUrl:
        "/images/blog/whats-new-in-v1-2/secret-roundtrips-after-subsequent.png",
      caption: "Secret key roundtrips after for subsequent connections",
    },
  ]}
/>

## Migrating to v1.2

Single-room tokens (the previous authentication method) generated through both
public and secret keys will continue to work for now, but will be deprecated in
the coming months. If you use public keys, tokens won’t be needed anymore in
v1.2. If you use secret keys, we recommend that you update your back end
endpoint to use the new methods. For most cases, we recommend access tokens, but
if you’re already using Liveblocks permissions, ID tokens may be the better
choice.

We’ve written [a migration guide](/docs/platform/upgrading/1.2) to help you
migrate.

## Contributors

Huge thanks to everyone who contributed and specifically to
[Chris Nicholas](https://twitter.com/ctnicholasdev) and
[Guillaume Salles](https://twitter.com/guillaume_slls) for the feedback and help
testing this out. Also a big shout out to our incredible community that keeps
jumping in to help us improve our infrastructure! Keep checking out the
[changelog](https://github.com/liveblocks/liveblocks/blob/main/CHANGELOG.md) for
the full release notes – see you next time!