Ownership Verification using REST

RESTful endpoints to perform verification of ownership without using the SDK

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:

Parameter

Description

ApiVersion

Set to EOS_ECOM_QUERYOFFERS_API_LATEST.

LocalUserId

The local user Epic account ID.

CatalogItemIds

The number of elements in EntitlementIds.

CompletionDelegate

Called when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature.

CatalogNamespace

Optional 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:

Parameter

Description

ApiVersion

Set to EOS_ECOM_QUERYOFFERS_API_LATEST.

LocalUserId

The local user Epic account ID.

CatalogItemIdCount

The quantity of Catalog items.

CompletionDelegate

Called when the operation completes using a EOS_Achievements_OnQueryDefinitionsCompleteCallback signature.

CatalogNamespace

Optional 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:

Claim

Description

jti

Set to A unique identifier for this token.

sub

The account ID that was used to request the token.

clid

The client ID used to request the token.

ent

An 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.

iat

The token expiration.

Below is the flow diagram:

OwnershipVerificationFlow.png