Skip to main content

​
Overview

In server environments (Node.js, Bun, Deno), RoZod needs explicit configuration for authentication. The configureServer function sets up cookies, API keys, and user agents that apply to all requests.

​
Basic setup

Configure authentication once at application startup: 
import { configureServer, fetchApi } from 'rozod';
import { getUsersUserdetails } from 'rozod/lib/endpoints/usersv1';

// Configure once at startup
configureServer({ 
  cookies: 'your_roblosecurity_cookie_here' 
});

// All subsequent requests automatically include the cookie
const userInfo = await fetchApi(getUsersUserdetails, { userIds: [123456] });
In browser environments, authentication works automatically using the user’s existing Roblox session.

​
Single account

For simple use cases with one Roblox account: 
import { configureServer } from 'rozod';

configureServer({
  cookies: '_|WARNING:-DO-NOT-SHARE-THIS...',
});
Never share or commit your .ROBLOSECURITY cookie. Treat it like a password.
Distribute requests across multiple accounts for higher rate limits: 
import { configureServer } from 'rozod';

configureServer({
  cookies: [
    'account1_roblosecurity_cookie',
    'account2_roblosecurity_cookie',
    'account3_roblosecurity_cookie',
  ],
});

// Requests automatically cycle through accounts
Control how cookies are selected from the pool:
Cycles through cookies sequentially:
configureServer({
  cookies: ['cookie1', 'cookie2', 'cookie3'],
  cookieRotation: 'round-robin', // Default for multiple cookies
});

// Request 1 uses cookie1
// Request 2 uses cookie2
// Request 3 uses cookie3
// Request 4 uses cookie1 again

​
OpenCloud API keys

For OpenCloud endpoints, configure your API key: 
import { configureServer } from 'rozod';

configureServer({ 
  cloudKey: 'your_opencloud_api_key_here' 
});

​
Combined configuration

Use both classic cookies and OpenCloud keys together: 
configureServer({
  cookies: ['account1', 'account2'],  // For classic *.roblox.com APIs
  cloudKey: 'your_opencloud_key',     // For apis.roblox.com/cloud/*
});
The API key is automatically applied only to OpenCloud endpoints (URLs containing /cloud/). Classic APIs use cookies.

​
User agent configuration

RoZod includes built-in browser user agents for server environments to avoid rate limiting.

​
Default behavior

User agents are applied automatically: 
configureServer({
  cookies: 'your_cookie',
  // userAgents automatically use built-in defaults
});

​
Custom user agents

Provide your own user agent pool: 
configureServer({
  cookies: 'your_cookie',
  userAgents: ['MyBot/1.0', 'MyService/2.0', 'MyApp/3.0'],
  userAgentRotation: 'round-robin', // or 'random' or 'none'
});

​
Disable user agents

Set to an empty array to disable: 
configureServer({
  cookies: 'your_cookie',
  userAgents: [], // No user agent header
});
Roblox is implementing cookie rotation for security. RoZod automatically detects rotated cookies and can notify you to persist the new values.

​
Basic refresh callback

import { configureServer } from 'rozod';

configureServer({
  cookies: process.env.ROBLOX_COOKIE,
  onCookieRefresh: async ({ oldCookie, newCookie, poolIndex }) => {
    // Persist the new cookie to your storage
    console.log('Cookie rotated!');
    console.log('Old cookie:', oldCookie);
    console.log('New cookie:', newCookie);
    console.log('Pool index:', poolIndex);
    
    // Update your storage
    await updateDatabaseCookie(poolIndex, newCookie);
  },
});
The internal cookie pool updates automatically, so the callback is only needed if you want to persist cookies across restarts.

​
Complete refresh example

import { configureServer } from 'rozod';
import { db } from './database';

configureServer({
  cookies: await db.getCookies(),
  onCookieRefresh: async ({ newCookie, poolIndex }) => {
    await db.updateCookie(poolIndex, newCookie);
    console.log(`Updated cookie ${poolIndex} in database`);
  },
});
Proactively refresh cookies before they expire: 
import { refreshCookie, getCookies, updateCookie } from 'rozod';

// Refresh a specific cookie
const result = await refreshCookie(0);

if (result.success) {
  console.log('New cookie:', result.newCookie);
  await db.updateCookie(0, result.newCookie);
} else {
  console.error('Refresh failed:', result.error);
}

// Refresh all cookies in a pool
const cookies = getCookies();
for (let i = 0; i < cookies.length; i++) {
  const result = await refreshCookie(i);
  if (result.success) {
    await db.updateCookie(i, result.newCookie);
  }
}

import { getCookies, updateCookie, clearServerConfig } from 'rozod';

// Get all current cookies
const allCookies = getCookies();
console.log(`Managing ${allCookies.length} cookies`);

// Manually update a cookie
updateCookie(0, 'new_cookie_value');

// Clear all configuration
clearServerConfig();

​
Configuration management

​
Reading configuration

import { getServerConfig } from 'rozod';

const config = getServerConfig();
console.log('Cookies:', config.cookies);
console.log('Cloud key:', config.cloudKey);
console.log('User agents:', config.userAgents);

​
Clearing configuration

import { clearServerConfig } from 'rozod';

// Remove all server configuration
clearServerConfig();

​
Updating configuration

import { configureServer } from 'rozod';

// Initial setup
configureServer({ cookies: 'cookie1' });

// Later, update configuration
configureServer({
  cookies: ['cookie1', 'cookie2'],
  cloudKey: 'new_api_key',
});

​
Security features

RoZod handles advanced Roblox security automatically:
1

XCSRF token management

Automatic CSRF token retrieval and caching for POST/PUT/DELETE requests.
2

Hardware-backed authentication (HBA)

Full support for Roblox’s hardware-backed authentication signatures.
3

Challenge handling

Captchas, 2FA, and other authentication challenges with custom handlers.
4

Cookie security

Secure cookie parsing, validation, and automatic rotation handling.

​
Challenge handler

For advanced authentication challenges: 
import { setHandleGenericChallenge } from 'rozod';

setHandleGenericChallenge(async (challenge) => {
  if (challenge.challengeType === 'captcha') {
    // Integrate with captcha solving service
    const solution = await solveCaptcha(challenge.challengeId);
    return {
      challengeType: challenge.challengeType,
      challengeId: challenge.challengeId,
      challengeBase64Metadata: solution,
    };
  }
  
  // Return undefined to skip the challenge
  return undefined;
});

​
Custom HBA keys

For Node.js environments requiring custom hardware-backed auth: 
import { changeHBAKeys } from 'rozod';

const keyPair = await crypto.subtle.generateKey(
  { name: 'ECDSA', namedCurve: 'P-256' },
  true,
  ['sign', 'verify']
);

changeHBAKeys(keyPair);

​
Environment-specific setup

import { configureServer } from 'rozod';
import * as dotenv from 'dotenv';

dotenv.config();

configureServer({
  cookies: process.env.ROBLOX_COOKIE,
  cloudKey: process.env.ROBLOX_CLOUD_KEY,
});

​
Best practices

1

Use environment variables

Store sensitive credentials in environment variables, never in code:
configureServer({
  cookies: process.env.ROBLOX_COOKIE,
  cloudKey: process.env.ROBLOX_CLOUD_KEY,
});
2

Configure once at startup

Call configureServer once when your application starts, not before each request.
3

Handle cookie rotation

Implement onCookieRefresh to persist rotated cookies:
configureServer({
  cookies: await loadCookiesFromStorage(),
  onCookieRefresh: async ({ newCookie, poolIndex }) => {
    await saveCookieToStorage(poolIndex, newCookie);
  },
});
4

Use cookie pools for high volume

Distribute load across multiple accounts to avoid rate limits:
configureServer({
  cookies: [
    process.env.ROBLOX_COOKIE_1,
    process.env.ROBLOX_COOKIE_2,
    process.env.ROBLOX_COOKIE_3,
  ],
  cookieRotation: 'round-robin',
});

​
Next steps

OpenCloud

Learn about using OpenCloud API keys

Basic requests

Start making authenticated requests

Build docs developers (and LLMs) love

Get started for freeTalk to us