roblox-bat

roblox-bat

Handles x-bound-auth-token generation for extension sand some other types of applications.

[!IMPORTANT] If you extract credentials from the Roblox app, or handle authentication with Roblox.com in your application without secureAuthenticationIntent in the login request model, you do not need to use this library. It is primarily intended for extensions and some applications.

As of 2026, it is unknown when enforcement will begin again. DevForum post: https://devforum.roblox.com/t/introducing-account-session-protection/2668306

What is x-bound-auth-token

A token generated by the client based on request body and epoch timestamp to give to the server in the headers to "verify itself" as the original session. The crypto key pair is stored in an Indexed DB and is used to sign further requests. The crypto key is generated on authentication (login, signup), it is per-session and is used as hardware-backed authentication.

There is an article on this feature: https://en.help.roblox.com/hc/en-us/articles/18765146769812-Account-Session-Protection, it also details on how to disable it. However, for extensions, asking the user to disable session protection is not feasible, especially when Open Cloud development is slow and extremely restricting.

How it Works

• On the first request, it will fetch metadata from https://www.roblox.com/charts in the meta[name="hardware-backed-authentication-data"] element.
• Any requests to generate a token will check if the URL is supported, and then grab a private key from the Indexed DB hbaStore in the hbaObjectStore with the key hba_keys. The final x-bound-auth-token key should be formatted like:
  • Currently: v1|sha256ofrequestbody|timestamp|signature1|signature2
• If the URL is supported and it could find a key, generateBaseHeaders will return {"x-bound-auth-token": string}, otherwise {}

Usage

In the Browser, it must be in a context where it has access to www.roblox.com's indexedDB. This is also a likely reason why web.roblox.com was merged into www.roblox.com.

const hbaClient = new HBAClient({
    onSite: true,
});

In server-side runtimes (Bun, NodeJS, Deno), you will have to supply the key yourself or generate one BEFORE authentication:

const hbaClient = new HBAClient({
    keys: await crypto.subtle.generateKey(
        {
            name: "ECDSA",
            namedCurve: "P-256",
        },
        false,
        ["sign"],
    ),
    // We need to supply the cookie to tell that the client is authenticated, otherwise we can set hbaClient.isAuthenticated externally.
    cookie: ".ROBLOSECURITY=...",
});

• GET Requests

import { HBAClient } from "roblox-bat";

const hbaClient = new HBAClient({
    onSite: true,
    // Or use "keys": CryptoKeyPair
});
// {"x-bound-auth-token": string}
const headers = await hbaClient.generateBaseHeaders(
    "https://users.roblox.com/v1/users/authenticated",
    "GET",
    true, // set to false or undefined if not authenticated
);

await fetch("https://users.roblox.com/v1/users/authenticated", {
    headers,
    credentials: "include",
});

• Requests with a body (POST, PUT, PATCH, DELETE)

import { HBAClient } from "roblox-bat";

const hbaClient = new HBAClient({
    onSite: true,
    // Or use "keys": CryptoKeyPair
});
const body = JSON.stringify({
    items: [
        {
            itemType: "Asset",
            id: 1028593,
        },
    ],
});
// {"x-bound-auth-token": string}
const headers = await hbaClient.generateBaseHeaders(
    "https://catalog.roblox.com/v1/catalog/items/details",
    "POST",
    true, // set to false or undefined if not authenticated
    body,
);

await fetch("https://catalog.roblox.com/v1/catalog/items/details", {
    method: "POST",
    headers: {
        ...headers,
        "content-type": "application/json",
    },
    body,
    credentials: "include",
});