> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PlayFab integration for XBOX services titles

> Sign players in to XBOX services and PlayFab, provision linked accounts, and wire up Microsoft Store in-app purchase via PlayFab economy for GDK titles.

PlayFab is Microsoft's backend-as-a-service for live games — economy, catalogs, leaderboards, cloud script, analytics, matchmaking, and PlayFab Party voice/data networking. It layers cleanly on top of XBOX services. XBOX services owns the **player-facing identity** (gamertag, friends, achievements, presence, MPSD sessions), and PlayFab owns the **backend live-service data** (inventory, currency, custom user data, telemetry).

Any GDK title that uses **PlayFab Party**, PlayFab economy for **Microsoft Store in-app purchase**, PlayFab leaderboards, or any other PlayFab service must sign the player into **both** stacks and keep the two identities linked.

<Info>
  This page focuses on the XBOX-side of the integration — how to provision a PlayFab account tied to the signed-in XUser, and how the Microsoft Store entitlement flow plumbs into PlayFab economy. For the full PlayFab feature surface (Game Manager, catalogs, cloud script, matchmaking, Party), see the [PlayFab documentation](https://learn.microsoft.com/gaming/services/playfab/).
</Info>

## XBOX and PlayFab user accounts

An XBOX services account and a PlayFab account are two separate identities:

* **XBOX services account** — player-facing. Owned by the player's Microsoft Account (MSA). Carries gamertag, XUID, friends, achievements, presence.
* **PlayFab account** — behind-the-scenes. Identified by an **Entity ID** inside your **PlayFab TitleId** (a 4–6 hex-digit string assigned when you create a title in [PlayFab Game Manager](https://developer.playfab.com/)). Not the same as your XBOX title ID.

To use any PlayFab feature (Party voice chat, economy, leaderboards) in your GDK title, every signed-in XUser must have a linked PlayFab account provisioned in the context of your PlayFab title. By the end of the sign-in flow:

* The player has been added with `XUserAddAsync` and holds an `XUserHandle`.
* A PlayFab account exists for that player under your PlayFab TitleId (auto-provisioned on first sign-in).
* The XBOX and PlayFab accounts are linked, and the title holds valid credentials (Entity ID + PlayFab token) for authenticated PlayFab REST/SDK calls.

<Warning>
  Your PlayFab **TitleId is not the same as your XBOX title ID**. Provision one PlayFab title per game (or per shard) in PlayFab Game Manager and hard-code that TitleId in your build config.
</Warning>

## Sign players in to PlayFab

There are two supported sign-in paths. Pick one based on which PlayFab services you use:

<CardGroup cols={2}>
  <Card title="PlayFab Services SDK" icon="star" href="#playfab-services-sdk-recommended">
    **Recommended for all titles.** Ships as a Gaming Extension Library (`PlayFab.Services.C`) in the GDK. Use for economy, leaderboards, cloud script, matchmaking, and any title that uses **more than just Party**.
  </Card>

  <Card title="PlayFab Party Xbox Live Helper Library" icon="headset">
    Use only if **PlayFab Party is the sole PlayFab service** you use and XBOX services is your only auth provider. Ships with the PlayFab Party SDK inside the GDK.
  </Card>
</CardGroup>

### PlayFab Services SDK (recommended)

The PlayFab Services SDK ships with the GDK and exposes `PFAuthenticationLoginWithXUserAsync`, which takes an `XUserHandle` and signs the player into PlayFab in one call. Set `createAccount = TRUE` to auto-provision the linked PlayFab account on first run.

**Set up**

1. Install the [GDK](https://aka.ms/gdkdl).
2. Add the **PlayFab.Services.C** Gaming Extension Library to your project:
   * Open the project in Visual Studio → **Project** → **Properties**.
   * Under **Configuration Properties** → **Gaming Desktop** → **General**, open **Gaming Extension Libraries** and add **PlayFab.Services.C**.

**Recommended sign-in flow**

1. Sign the player into their XBOX account with [`XUserAddAsync`](/reference/system/xuser/xuser_members) and hold onto the returned `XUserHandle`.
2. Call `PFAuthenticationLoginWithXUserAsync`:
   * Pass the `XUserHandle` as the `user` parameter.
   * Set `createAccount = TRUE` so PlayFab auto-provisions a linked account on first sign-in.
3. Persist the resulting PlayFab credentials (Entity ID + PlayFab token) for the session and use them for all subsequent PlayFab calls.

See the [PlayFab Services SDK Quickstart for GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart) for the full walkthrough.

### PlayFab Party XBOX Live Helper Library

If PlayFab Party is the **only** PlayFab service your title uses, you can skip the PlayFab Services SDK and sign in via the Party XBOX Live Helper Library, which is bundled with the PlayFab Party SDK in the GDK.

**Flow**

1. Sign the player into XBOX with `XUserAddAsync`.
2. When chat is first initiated, retrieve the XUID with `XUserGetId`.
3. Create a **`PartyXblLocalChatUser`** by calling `PartyXblManager::CreateLocalChatUser` with the XUID.
4. Call `PartyXblManager::LoginToPlayFab` with that user object.
   * On GDK (console and PC) and XDK, the helper library internally fetches the required XBOX services token, signs the player into PlayFab using their XBOX credentials, and auto-creates a PlayFab account on first sign-in. Accounts created this way have no email or username attached.
   * On non-GDK/non-XDK titles (for example, PC Win32 without GDK) you receive a `PartyXblTokenAndSignatureRequestedStateChange` instead. Fetch the XBOX services token yourself and pass it back via `PartyXblManager::CompleteGetTokenAndSignatureRequest`.
5. On success you receive a `PartyXblLoginToPlayFabCompletedStateChange` carrying the PlayFab Entity ID and token.

<Note>
  For **remote** users, use `PartyXblManager::CreateRemoteChatUser` — no authentication or token exchange is required for the remote user flow.
</Note>

## XUser is the identity bridge

Everything downstream — PlayFab sign-in, MPSD session write tokens, S2S calls, entitlement queries — begins with an `XUserHandle` returned from `XUserAddAsync`. Two APIs matter for PlayFab integration:

| API                                                      | Purpose                                                                                                                 |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [`XUserAddAsync`](/reference/system/xuser/xuser_members) | Sign the player into their XBOX account and get an `XUserHandle`.                                                       |
| `XUserGetTokenAndSignatureUtf16Async`                    | Retrieve an XBOX services token + signature for the helper-library path (Win32 fallback), or for any custom S2S bridge. |

See [XBOX services identity](/services/xbox-services/fundamentals/identity/xs-identity-overview) for the wider sign-in model (MSA, XSTS tokens, sandbox scoping).

## Cross-platform titles

PlayFab supports many platform auth providers. When you ship the same title on iOS, Android, Steam, or PlayStation, do **not** try to route every player through XUser — use the platform's native PlayFab auth provider:

* **iOS** — Apple ID (`LoginWithApple`).
* **Android** — Google Play Games (`LoginWithGoogleAccount`).
* **Steam** — `LoginWithSteam`.
* **XBOX / GDK PC** — `PFAuthenticationLoginWithXUserAsync` (this page).

Each platform sign-in provisions its own PlayFab account and links it to the same PlayFab title. Players who move across platforms with the same PlayFab account get their linked identities merged inside PlayFab.

See [Platform-specific PlayFab authentication](https://learn.microsoft.com/gaming/services/playfab/features/authentication/platform-specific-authentication/) for the full matrix.

## Microsoft Store in-app purchase via PlayFab economy

For GDK titles that sell in-app items through the Microsoft Store, PlayFab acts as the **economy backend** while the Microsoft Store handles the actual transaction. PlayFab reconciles Microsoft Store purchases into the player's PlayFab inventory using the **entitlement method** — the player must be signed into their XBOX account first.

### The flow

1. Player is signed in to XBOX (`XUserAddAsync`) and PlayFab (`PFAuthenticationLoginWithXUserAsync`).
2. Player buys an item through the Microsoft Store on-device.
3. Your title notifies PlayFab of the purchase.
4. PlayFab calls [`ConsumeMicrosoftStoreEntitlements`](https://learn.microsoft.com/rest/api/services/playfab/client/platform-specific-methods/consume-microsoft-store-entitlements) with the XBOX token and syncs the player's PlayFab inventory, granting any new items.

<Warning>
  For GDK titles use the **Microsoft Store** PlayFab add-on and `ConsumeMicrosoftStoreEntitlements`. Do **not** use the legacy XBOX add-on / `ConsumeXboxEntitlements` (that path is for XDK titles only). The Universal Windows Platform add-on is deprecated.
</Warning>

### Partner Center prerequisites

* Enrolled in the [XBOX Creators Program](https://www.xbox.com/developers/creators-program) or a Managed Partner.
* Publisher identity configured in Partner Center with the same publisher GUID as your XBOX business partner information (`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`).
* Concept approval to use XBOX services.

In Partner Center, under **Game setup → XBOX services**, choose either **Use full XBOX services feature set (requires concept approval)** or **Use XBOX Creators Program**, then create your add-ons under your title.

<Note>
  PlayFab's Microsoft Store add-on **does not support store-managed consumables** in Partner Center. Create **developer-managed consumables** (or durables) only.
</Note>

### Create matching items in Partner Center and PlayFab

The **Product ID** in Partner Center and the **Item ID** in PlayFab must match exactly for entitlement sync to work.

1. In Partner Center → **Add-ons** → **Create a new Consumable (Developer-managed)** (or Durable). Enter a unique **Product ID** (for example, `MyItem_001`).
2. In [PlayFab Game Manager](https://developer.playfab.com/) → **Engage** → **Economy** → **New item**. Enter the same string in **Item ID** (`MyItem_001`). Mark it Consumable or Durable to match Partner Center, and save.

### Terminology reference

| Concept               | PlayFab    | Partner Center / Microsoft Store   |
| --------------------- | ---------- | ---------------------------------- |
| Unique identifier     | Item ID    | Product ID                         |
| Consumable            | Consumable | Consumable (Developer-managed)     |
| Durable               | Durable    | Durable *or* Durable with packages |
| Virtual in-game store | Store      | *(n/a)*                            |

### Catalogs and Stores — one Item ID globally

PlayFab lets you define multiple **Catalogs** per title, and within each Catalog you can group items into **Stores**. For Microsoft Store entitlement sync to work, **each Product ID must match exactly one Item ID across all Catalog versions in your PlayFab title.**

<Warning>
  If the same `Item ID` appears in more than one Catalog, entitlement consumption will fail. Keep item IDs globally unique across every Catalog in a given PlayFab title.
</Warning>

**Wrong — same ID reused across catalogs:**

| Catalog version | Item ID     | Type       |
| --------------- | ----------- | ---------- |
| MyCatalog\_001  | MyItem\_001 | Consumable |
| MyCatalog\_002  | MyItem\_001 | Consumable |
| MyCatalog\_003  | MyItem\_001 | Durable    |

**Right — one Item ID per SKU, reused across Stores freely:**

| Catalog version | Item ID     | Type       |
| --------------- | ----------- | ---------- |
| MyCatalog\_001  | MyItem\_001 | Consumable |
| MyCatalog\_001  | MyItem\_002 | Durable    |
| MyCatalog\_002  | MyItem\_003 | Consumable |
| MyCatalog\_003  | MyItem\_004 | Durable    |

Stores inside a Catalog can then bundle any subset of those unique items freely:

| Store ID     | Item IDs                              |
| ------------ | ------------------------------------- |
| MyStore\_001 | MyItem\_001, MyItem\_002              |
| MyStore\_002 | MyItem\_001                           |
| MyStore\_003 | MyItem\_002, MyItem\_003, MyItem\_004 |

## See also

* [XBOX services identity](/services/xbox-services/fundamentals/identity/xs-identity-overview) — XUser, MSA, XSTS tokens, sandbox scoping.
* [XBOX multiplayer](/services/xbox-services/multiplayer/index) — PlayFab Party as a multiplayer transport option.
* [Game Chat 2](/services/xbox-services/multiplayer/chat/game-chat2/game-chat-2-intro) — Game Chat 2 layered on top of PlayFab Party.
* [Multiplayer Activity](/services/xbox-services/multiplayer/mpa/live-mpa-overview) — MPA + PlayFab Party integration.
* [PlayFab Services SDK Quickstart for GDK](https://learn.microsoft.com/gaming/services/playfab/sdks/gdk/quickstart)
* [PlayFab pricing](https://playfab.com/pricing/)


## Related topics

- [Identity](/xbox-services/identity.md)
- [Multiplayer](/xbox-services/multiplayer.md)
- [Game Chat](/xbox-services/game-chat.md)
- [Multiplayer Activity](/xbox-services/multiplayer-activity.md)