# @xboxreplay/xboxlive-auth

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

Latest version **5.1.0** (published 2025-08-25) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @xboxreplay/xboxlive-auth
pnpm add @xboxreplay/xboxlive-auth
yarn add @xboxreplay/xboxlive-auth
bun add @xboxreplay/xboxlive-auth
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2025-08-25 |
| First published | 2019-02-03 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=16.0.0 |
| Dependencies | 0 |
| Unpacked size | 110.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 115 |
| Author | Alexis Bize |
| Maintainers | zeny |
| Keywords | xboxnetwork, xboxreplay, xboxlive, xbox, live, auth |

## Links

- npm: https://www.npmjs.com/package/@xboxreplay/xboxlive-auth
- Repository: https://github.com/XboxReplay/xboxlive-auth
- Homepage: https://github.com/XboxReplay/xboxlive-auth#readme
- Issues: https://github.com/XboxReplay/xboxlive-auth/issues
- npm.io page: https://npm.io/package/@xboxreplay/xboxlive-auth

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 5.1.0 (latest) — 2025-08-25
- 5.0.0-beta.4 (beta) — 2025-05-27
- 5.0.2 — 2025-06-16
- 5.0.1 — 2025-05-27
- 5.0.0 — 2025-05-27
- 5.0.0-beta.3 — 2025-05-27
- 5.0.0-beta.2 — 2025-05-27
- 5.0.0-beta.1 — 2025-05-27
- 4.1.0 — 2024-12-09
- 4.0.0 — 2021-07-26
- 4.0.0-beta.5 — 2021-02-25
- 4.0.0-beta.4 — 2021-02-21
- 4.0.0-beta.3 — 2021-02-19
- 4.0.0-beta.2 — 2021-02-19
- 4.0.0-beta.1 — 2021-01-17
- … 22 more at https://npm.io/package/@xboxreplay/xboxlive-auth/versions

## README

# 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](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/90-Migration_From_v4.md) 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

```bash
npm install @xboxreplay/xboxlive-auth
```

## Quick Start

### Basic Authentication

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

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

### Response Format

```json
{
  "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

```typescript
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

```typescript
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:

```typescript
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](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/01-Authenticate.md)
-   [Use a custom Azure Application (OAuth2.0)](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/02-Custom_Azure_Application.md)
-   [Experimental methods, such as "deviceToken" generation](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/03-Experimental.md)
-   [What's a RelyingParty and how to use it](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/04-RelyingParty.md)
-   [Available methods in this library](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/05-Methods.md)
-   [Known issues and possible workarounds](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/06-Known_Issues.md)
-   [How to deal with unauthorized "AgeGroup" authentication](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/07-Detect_Unauthorized_AgeGroup.md)

## Using the XSAPI Client

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

```typescript
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

```bash
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](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/01-Authenticate.md). Additional improvements regarding this issue are not currently planned.

### Other Issues

Please refer to the [dedicated documentation](https://github.com/XboxReplay/xboxlive-auth/blob/master/docs/06-Known_Issues.md) for other known issues and workarounds.

## License

[Apache Version 2.0](https://github.com/XboxReplay/xboxlive-auth/blob/master/LICENSE)

---
_Source: https://npm.io/package/@xboxreplay/xboxlive-auth · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._