xbox playfab
commands need Admin permission on the title they act on; see
How PlayFab authentication works. Unattended jobs can sign
in as a service principal instead; see
Automation (service principal) authentication.
Sign in
auth login opens your system browser to sign in, then reports the account and when its token
expires:
xbox auth login again and choose
the other account. Every later command uses it, including in other terminals for your OS user.
See Auth.
Check status
auth status shows the cached account and its token. It doesn’t check that you can use
PlayFab or Partner Center.
--output json and check signedIn. A nonzero exit means the CLI couldn’t
read its settings or token cache.
Saved defaults, such as the seller or PlayFab title, are separate from sign-in. See
Context.
Sign out
auth logout removes the cached accounts and tokens, which signs out every terminal for your
OS user. It keeps your saved context.
Token cache
Commands reuse and refresh your cached token, so runxbox auth login again only when the CLI
asks you to. The token is stored in the Windows protected cache, the macOS Keychain, or the
Linux Secret Service keyring. On Linux without a usable keyring, such as a headless machine, the
CLI warns and uses an unencrypted file protected only by file permissions.
How PlayFab authentication works
Forxbox playfab commands, the CLI sends your Entra ID access token to PlayFab, so you never
handle a PlayFab title secret key. PlayFab checks that your account has Admin permission on
the title, or on the studio for the
playfab service-principal commands. A Studio Admin
grants it in PlayFab’s Game Manager, for example with the built-in Title Admin role; see
PlayFab user roles.
A service principal gets PlayFab access only
when a person grants it with xbox playfab service-principal set. A service principal can’t
manage grants itself.
See PlayFab API integration for selecting a title and calling PlayFab APIs.
Overriding Entra ID settings
The Entra ID application used for sign-in is built into the CLI. Most users don’t need to change it. You can override itsAzureAd settings with XBOX_AZUREAD__ environment variables, such as
XBOX_AZUREAD__CLIENTID, or for one command with these options:
See Configuration for all settings.
Automation (service principal) authentication
A service principal can sign in, and
auth status reports a valid token, but its calls fail
with an authorization error until the service accepts it. PlayFab accepts it after a person
grants it access with
xbox playfab service-principal set. Other
commands that call an online service, such as xbox game and xbox xbl, don’t accept
service principals yet; see
Known issues.XBOX_AUTHENTICATION__MODE to a service-principal mode, and each command gets
an app-only Entra ID token as the configured app registration or managed identity. Nothing is
cached, and auth login and auth logout fail.
A service principal has no saved context, so pass the seller and title with their options or
XBOX_ variables. See Context.
TENANTIDmust be a tenant GUID or verified domain, notcommon,organizations, orconsumers.CLIENTIDmust be a GUID.- These settings come only from environment variables.
--client-idand--tenant-idare refused in a service-principal mode;--scopesstill applies. - In
azureclimode, select the identity by signing in to the Azure CLI. Inmanagedidentitymode, the identity determines the tenant. - The CLI never falls back to another mode or to a cached user sign-in. An unknown mode, a missing setting, a setting the mode doesn’t use, or an unreadable credential file fails with an error that names the variable.
Examples
A client secret on Linux or macOS, read from a file.$RUNNER_TEMP is GitHub Actions’ temporary
folder; elsewhere, use any file that only the job can read:
az login --service-principal:
AZURE_CONFIG_DIR.
In Azure Pipelines, run xbox inside an AzureCLI@2 task with an Azure Resource Manager service
connection, preferably one that uses workload identity federation. The service connection selects
the tenant and identity, so don’t set XBOX_AUTHENTICATION__TENANTID or
XBOX_AUTHENTICATION__CLIENTID. Replace the service connection name with your own:
Set up GitHub Actions
githuboidc mode signs a GitHub Actions job in as a service principal in your Entra ID tenant,
with no secret to store or rotate. The CLI requests the job’s OIDC token from GitHub, and Entra
ID exchanges it for an access token if it matches a federated credential on your app
registration. The federated credential decides which jobs can sign in; it doesn’t grant access
to any API.
To create the app registration, its service principal, and a federated credential that trusts
your repository, follow
Configuring OpenID Connect in Azure
and
Create a trust relationship between an app and an external identity provider.
Skip the azure/login step and Azure role assignments in those guides, because the CLI requests
the token itself and doesn’t call Azure Resource Manager.
The setup must meet these requirements:
- The federated credential uses the issuer
https://token.actions.githubusercontent.comand the audienceapi://AzureADTokenExchange. - Its subject matches the subject GitHub issues for the job’s environment. The earlier
default is
repo:<OWNER>/<REPO>:environment:<ENVIRONMENT>. On GitHub.com, repositories created, renamed, or transferred after July 15, 2026 userepo:<OWNER>@<OWNER-ID>/<REPO>@<REPO-ID>:environment:<ENVIRONMENT>; see GitHub’s immutable subject guidance. Organizations and repositories can also customize subjects. - The job declares that environment and
permissions: id-token: write. Without the environment, GitHub presents a branch or pull request subject, and Entra ID refuses it. - The job sets
XBOX_AUTHENTICATION__MODE,XBOX_AUTHENTICATION__TENANTID, andXBOX_AUTHENTICATION__CLIENTID, as in the example. The tenant and client IDs aren’t secrets, so store them as environment variables and read them throughvars.
pull_request_target workflow runs with the base repository’s permissions and can request an
OIDC token, even for a pull request from a fork. Never check out or run untrusted pull request
code in a job that can sign in as the service principal.
If the subject doesn’t match, Entra ID refuses the token with AADSTS700213 (“No matching
federated identity record found for presented assertion subject ’…’”). The error quotes the
subject GitHub sent, so compare it with the credential’s subject.
To keep each environment’s settings with the environment, store them as GitHub environment
variables named after the CLI’s variables, such as XBOX_AUTHENTICATION__CLIENTID, and pass
them to the CLI unchanged.
Confirm the identity
In a service-principal mode,auth status gets a token and reports the mode, principal type,
tenant, app ID, object ID, audience, and app roles. It never prints the token. If it can’t get
a token, it exits 1, so a pipeline step that runs it fails. See
Auth.
The objectId is the service principal’s object ID, not the app registration’s. Pass it as
--principal-object-id to xbox playfab service-principal set to grant the service principal
PlayFab access.