This endpoint lets your application server (your back end) obtain a token that one of its clients (your frontend) can use to enter a Liveblocks room. You use this endpoint to implement your own application’s custom authentication endpoint. When making this request, you’ll have to use your secret key.

Important: The difference with an ID token is that an access token holds all the permissions, and is the source of truth. With ID tokens, permissions are set in the Liveblocks back end (through REST API calls) and "checked at the door" every time they are used to enter a room.

Note: When using the @liveblocks/node package, you can use Liveblocks.prepareSession in your back end to build this request.

You can pass the property userId in the request’s body. This can be whatever internal identifier you use for your user accounts as long as it uniquely identifies an account. The property userId is used by Liveblocks to calculate your account’s Monthly Active Users. One unique userId corresponds to one MAU.

Additionally, you can set custom metadata to the token, which will be publicly accessible by other clients through the user.info property. This is useful for storing static data like avatar images or the user’s display name.

Lastly, you’ll specify the exact permissions to give to the user using the permissions field. This is done in an object where the keys are room names, or room name patterns (ending in a *), and a list of permissions to assign the user for any room that matches that name exactly (or starts with the pattern’s prefix). For tips, see Manage permissions with access tokens.

{
  "userId": "user-123",
  "userInfo": {
    "name": "bob",
    "avatar": "https://example.org/images/user123.jpg"
  },
  "organizationId": "acme-corp",
  "permissions": {
    "my-room-1": [
      "*:write"
    ],
    "my-room-2": [
      "*:write"
    ],
    "my-room-*": [
      "*:read"
    ]
  }
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."
}