Skip to Content
better-auth-plugins

Xbox

Sign in with Xbox (Microsoft account, then Xbox Live), for Xbox developers.

Xbox sign-in uses a Microsoft account, then Xbox Live. Install and set up the authentication plugin first; this page covers what is specific to Xbox.

Xbox developers only

In practice, Microsoft allows the xboxlive.signin scope only for apps enrolled in the Xbox developer program (ID@Xbox and partners); other apps report an "Invalid app registration" error. Without access, consider Microsoft sign-in through better-auth's microsoft provider instead; it signs in with the same account, without Xbox data.

Get your credentials

This follows Microsoft's Xbox services sign-in for title websites:

  1. Register an app in Microsoft Entra ID with Personal Microsoft accounts only and the redirect URL https://<your app>/api/auth/callback/xbox.
  2. Create a client secret; use the application id and secret as clientId and clientSecret.

Configure the provider

auth.ts
import { betterAuth } from "better-auth";
import { authentication } from "@checodo/better-auth-authentication";

export const auth = betterAuth({
  plugins: [
    authentication({
      xbox: {
        clientId: process.env.XBOX_CLIENT_ID!,
        clientSecret: process.env.XBOX_CLIENT_SECRET!,
      },
    }),
  ],
});

Sign in

await authClient.signIn.social({ provider: "xbox", callbackURL: "/dashboard" });

To link Xbox to a signed-in user, see Link an account.

Provider notes

At sign-in, the plugin asks for xboxlive.signin (and xboxlive.offline_access with offlineAccess: true), exchanges the Microsoft token for an Xbox user token and then an XSTS token, and reads the player from its claims: the XUID (xid, the account id) and the gamertag (gtg, the name).

  • relyingParty (default http://xboxlive.com) and sandboxId (default RETAIL) choose the XSTS token. Xbox partners with a relying party of their own can use it.
  • A Microsoft account without an Xbox profile can't sign in: XSTS refuses it, and the reason (an XErr code, without the response) is logged.
  • The Xbox tokens aren't stored; the account keeps the Microsoft tokens, like any provider.
  • Xbox shares no email: players get <XUID>@xbox.invalid, see Placeholder emails.

Options

xbox takes these, plus the options every provider accepts:

Prop

Type

On this page