XboxReplay/XboxLive-Auth

A lightweight, zero-dependency Xbox Network (Xbox Live) authentication library for Node.js with OAuth 2.0 support.

⚠️ Breaking Changes Notice: Significant breaking changes have been introduced since v4. Please review the Migration Guide for detailed upgrade instructions and code examples.

Important

The main authenticate() function remains backward compatible for basic usage, but method imports and advanced features have changed significantly.

Installation

npm install @xboxreplay/xboxlive-auth

Quick Start

Basic Authentication

import { authenticate } from '@xboxreplay/xboxlive-auth';

authenticate('name@domain.com', 'password').then(console.info).catch(console.error);

Response Format

{
  "xuid": "2584878536129841",
  "user_hash": "3218841136841218711",
  "xsts_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "display_claims": {
    "gtg": "Zeny IC",
    "xid": "2584878536129841",
    "uhs": "3218841136841218711",
    "agg": "Adult",
    "usr": "234",
    "utr": "190",
    "prv": "185 186 187 188 191 192 ..."
  },
  "expires_on": "2025-04-13T05:43:32.6275675Z"
}

Note

The xuid field may be null based on the specified "RelyingParty", and display_claims may vary based on the specified "RelyingParty" configuration.

Advanced Usage

Raw Response Mode

import { authenticate } from '@xboxreplay/xboxlive-auth';

// Get raw responses from all authentication steps
const rawResponse = await authenticate('email@example.com', 'password', {
  raw: true,
});

console.log(rawResponse);
// Returns:
// {
//   'login.live.com': LiveAuthResponse,
//   'user.auth.xboxlive.com': XNETExchangeRpsTicketResponse,
//   'xsts.auth.xboxlive.com': XNETExchangeTokensResponse
// }

Custom Authentication Options

import { authenticate } from '@xboxreplay/xboxlive-auth';

const result = await authenticate('email@example.com', 'password', {
  XSTSRelyingParty: 'http://xboxlive.com',
  optionalDisplayClaims: ['gtg', 'xid'],
  sandboxId: 'RETAIL',
});

Using Individual Modules

The library now exports granular modules for advanced use cases:

import { live, xnet } from '@xboxreplay/xboxlive-auth';

// Microsoft Live authentication
await live.preAuth();
await live.authenticateWithCredentials({ email: 'user@example.com', password: 'password' });
await live.exchangeCodeForAccessToken(code);
await live.refreshAccessToken(refreshToken);

// Xbox Network token exchange
await xnet.exchangeRpsTicketForUserToken(accessToken, 't');
await xnet.exchangeTokensForXSTSToken(tokens, options);

// Experimental features
const deviceToken = await xnet.experimental.createDummyWin32DeviceToken();

Type Safety

The library is fully typed with TypeScript. Key types include:

• Email: Enforces proper email format (${string}@${string}.${string})
• AuthenticateOptions: Configuration options for authentication
• AuthenticateResponse: Standard response format
• AuthenticateRawResponse: Raw response format when raw: true

Documentation

• Basic authentication
• Use a custom Azure Application (OAuth2.0)
• Experimental methods, such as "deviceToken" generation
• What's a RelyingParty and how to use it
• Available methods in this library
• Known issues and possible workarounds
• How to deal with unauthorized "AgeGroup" authentication

Using the XSAPI Client

The library includes an XSAPI client that's a Fetch wrapper designed specifically for calling Xbox Network APIs:

await XSAPIClient.get('https://profile.xboxlive.com/users/gt(Major%20Nelson)/profile/settings?settings=Gamerscore', {
  options: { contractVersion: 2, userHash: 'YOUR_USER_HASH', XSTSToken: 'YOUR_XSTS_TOKEN' },
});

Manual cURL Example

curl 'https://profile.xboxlive.com/users/gt(Major%20Nelson)/profile/settings?settings=Gamerscore' \
  -H 'Authorization: XBL3.0 x=YOUR_USER_HASH;YOUR_XSTS_TOKEN' \
  -H 'X-XBL-Contract-Version: 2'

Known Limitations

Two-Factor Authentication (2FA)

The exposed authenticate method cannot deal with 2FA, but a workaround may be possible using OAuth2.0 flows with refresh tokens. Please take a look at the authenticate documentation. Additional improvements regarding this issue are not currently planned.

Other Issues

Please refer to the dedicated documentation for other known issues and workarounds.

License

Apache Version 2.0