By Peter Gustafson

The Ecom Interface provides two methods for ownership verification. The first is the online method.

Online Method

The online method integrates directly with the Epic Entitlement Service. It’s useful for trusted game servers or less-secure checks on client systems for simple validation.

To determine if a user owns a specific Catalog item, make a call to EOS_Ecom_QueryOwnership to get ownership information from the server. The callback receives a void pointer containing information about the user.

Make a call to EOS_Ecom_QueryOwnershipOptions using the parameters below:

ParameterDescription
ApiVersionSet to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserIdThe local user Epic account ID.
CatalogItemIdsThe number of elements in EntitlementIds.
CompletionDelegateCalled when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature.
CatalogNamespaceOptional product namespace.

EOS returns the data you requested (and your void pointer) stored in an EOS_Ecom_OnQueryOwnershipCallback structure. This structure contains an array of EOS_Ecom_EntitlementOwnership users. Items that the server doesn’t recognize are returned as not owned.

Offline Method

The second option is the offline method. It provides a signed token that the user verifies, or passes to a third-party service. When integrating with a third-party service for ownership verification, the offline method is recommended because it avoids granting the outside service access to the user’s data.

To check ownership and cache the results locally, make a call to EOS_Ecom_QueryOwnershipToken. Use the parameters below:

ParameterDescription
ApiVersionSet to EOS_ECOM_QUERYOFFERS_API_LATEST.
LocalUserIdThe local user Epic account ID.
CatalogItemIdCountThe quantity of Catalog items.
CompletionDelegateCalled when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature.
CatalogNamespaceOptional product namespace.

Upon success, you will receive an EOS_Ecom_QueryOwnershipTokenCallbackInfo structure that includes a JSON Web Token (JWT) with a five-minute expiration time.

Verify the JWT with a public key and unpack it to extract the Key ID. Send the Key ID to third-party services if needed to verify the Entitlement information came from Epic Games Services (EGS).

Example

Below is an example request. Use this endpoint:

https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}

Below is the example response:

GET/ecommerceintegration/api/public/publickeys/pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g HTTP/1.1

Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com

{

"kty": "RSA",

"e": "AQAB",

"kid": "pbvnNIE97vErdePGIRoG41h8hnP_2wIxG8xbwZCIj3g",

"n": "gcStqtD8XD9c9ifNuxXT9Xd_EEZLLCw34yxINRQPt0MxEWkoOFsuisRWGktSFtGrnUuQnp8GQY0k4Pyl_yDItWAcRtO7JUjrhQnxx3xXp_0P8xJMH1ny-RcxHF3bEJWhDzNW5PBpBjQTQZis-83499z-4OlNA7oUnDKEJkqNfzh4mMDFluPxvW_Hwpaw71nhzJI7-N-BdsPsLdqUANajLsFKq9fr06Lek_tm-6-RUxNPE3yS0x0UIsGyapA4Apcczz0xTzRDfwOkq_TyKGZiZc7vtgjkWnqdsCyXZC7dzKJvg0ggO3mKXhqZNNC_2pz24o1X_xCbG8rXtuvX8-ux-Q"

}

Token Details

The Ownership Verification Token is a JWT signed using RS512 (RSA PKCS#1 signature with SHA-512, RSA key size 2048). The token contains the following claims:

ClaimDescription
jtiSet to A unique identifier for this token.
subThe account ID that was used to request the token.
clidThe client ID used to request the token.
entAn array of Entitlements that were verified for this token. If the value is empty, the account is not entitled to any of the requested Entitlements for a given sandboxId.
iatThe token expiration.

Below is the flow diagram: