- XBOX services client From a client that is authenticated with XBOX services. These calls are always within a user context.
- Service-to-service From a custom title web service through service-to-service XBOX services calls. These calls are either on behalf of a user or made directly as a service. For more information about calls from title services, see Title service calls to XBOX services.
Client calls to XBOX services
For all calls to XBOX services by using the Microsoft Game Development Kit (GDK), we strongly recommend that titles use the XBOX Service APIs (XSAPI) that are bundled with Microsoft Game Development Kit (GDK) releases. These APIs handle HTTP requests and return available service data through objects directly to a title. They also implement the connection and caching behavior that we recommend for XBOX services and authentication. For more information about these APIs, see the XBOX Service API documentation XSAPI reference. The following sections are provided only for completeness and a deeper understanding of XBOX services authentication.Initial setup
XBOX services are transparently preconfigured for all titles. No additional endpoint configuration is necessary. This applies for all*.xboxlive.com subdomains.
Token retrieval and connection flow
To use any XBOX services endpoint, an XSTS authentication token and message signature must be present. Without this information, communication with the service is rejected. The XSTS token and user identification (user hash) must be included in theAuthentication header of the request. The message signature must be specified in the Signature header of the request. For detailed information about the structure of these headers, see XBOX services security tokens (XSTS tokens).
Obtaining an XSTS token
The XSTS token and signature header data is obtained through the XUserGetTokenAndSignatureUtf16Async API. It provides the required headers for service requests. The title then requests the XSTS token for an XBOX services endpoint by using theXUserGetTokenAndSignatureUtf16Async API through the following flow.
- Call
XUserGetTokenAndSignatureUtf16Asyncon the current user. Include the URL of the XBOX services and required headers or message body in the API call. This API call retrieves the XSTS token for the XBOX services endpoint. The call generates a message signature for the message and predefined headers. - Retrieve the XSTS token and signature through
XUserGetTokenAndSignatureUtf16Resultfrom the asynchronous result.XUserGetTokenAndSignatureUtf16Resultreturns an encrypted XSTS token. Titles should treat the returned token as opaque data. Token data must not be written to disc or cached in title space beyond the subsequent service call. - Use Microsoft Windows HTTP Services (WinHTTP), xCurl, and the XSTS token as appropriate in the Authorization header of the HTTPS request.
Token expiration and refresh
An XSTS token is valid only for a specific duration. The default expiration time for an XSTS token is four hours. Each token contains a time stamp that is verified by all XBOX services. The XUserGetTokenAndSignatureUtf16Async API must be used for each new authentication or sign-in request.XUserGetTokenAndSignatureUtf16Async handles token expiration and caching. The API ensures that the title always receives a valid token. A title must not cache tokens otherwise.
When a token that is expired or not valid is presented to an XBOX services endpoint, an HTTP/401 error is returned.