Skip to main content

​
setHandleGenericChallenge

Allows you to set the function that will be used to handle Roblox generic challenges, such as captchas and two-step verification. When Roblox returns a challenge header in a response, RoZod will automatically invoke your handler function. Your handler should solve the challenge and return the solution, or return undefined to skip the challenge. 
function setHandleGenericChallenge(
  fn: (challenge: ParsedChallenge) => Promise<ParsedChallenge | undefined> | ParsedChallenge | undefined
): void

​
Parameters

​
fn
ChallengeHandler
required
The function to use for handling challenges.

​
Examples

import { setHandleGenericChallenge } from 'rozod';
import type { ParsedChallenge } from 'parse-roblox-errors';

setHandleGenericChallenge(async (challenge: ParsedChallenge) => {
  if (challenge.challengeType === 'captcha') {
    // Solve the captcha using your preferred service
    const solution = await solveCaptcha(challenge.challengeId);
    
    return {
      challengeType: challenge.challengeType,
      challengeId: challenge.challengeId,
      challengeBase64Metadata: solution,
    };
  }
  
  // Skip other challenge types
  return undefined;
});
RoZod automatically retries requests up to 3 times when challenges are returned. Your handler will be invoked for each retry until the challenge is solved or the retry limit is reached.
Make sure your challenge handler doesn’t throw errors. If it does, RoZod will catch and log them, but the request will fail. Always return undefined if you can’t handle a challenge type.

​
changeHBAKeys

Allows you to change the crypto key pair used by the internal hardware-backed authentication (HBA) signatures. This should only be used in a Node.js context. Roblox’s HBA system requires cryptographic signatures for certain authenticated requests. RoZod generates these automatically, but you can provide your own key pair if needed for advanced use cases. 
function changeHBAKeys(keys?: CryptoKeyPair): void

​
Parameters

​
keys
CryptoKeyPair
The crypto key pair to use for HBA signatures. Pass undefined to reset to automatic key generation.

​
Example

import { changeHBAKeys } from 'rozod';

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

// Use the custom key pair for HBA signatures
changeHBAKeys(keyPair);
This is an advanced feature. Most users don’t need to call this function - RoZod handles HBA signatures automatically. Only use custom keys if you have a specific requirement, such as persisting keys across application restarts for consistency.
Hardware-backed authentication (HBA) is a security feature implemented by Roblox to verify that requests come from legitimate clients. RoZod automatically generates the required cryptographic signatures using the Web Crypto API.

​
Types

​
ParsedChallenge

type ParsedChallenge = {
  challengeType: string;
  challengeId: string;
  challengeBase64Metadata: string;
}
Represents a Roblox authentication challenge that needs to be solved.

​
CryptoKeyPair

interface CryptoKeyPair {
  privateKey: CryptoKey;
  publicKey: CryptoKey;
}
Standard Web Crypto API key pair interface for ECDSA P-256 keys.

Build docs developers (and LLMs) love

Get started for freeTalk to us