Epic Online Services (EOS) provides multiple ways to verify an account's ownership of catalog items. The preferred method is to use the EOS SDK APIs through the Ecom Interface. This document is provided for titles and services that prefer to access ownership information via RESTful endpoints. EOS has RESTful service endpoints for direct online ownership verification, creating and validating an ownership token that can be passed between clients and services, and entitlements services for querying, enumerating and consuming entitlement records.
The method used for ownership verification depends on the use case. The online method can be used by your game client or your game server by integrating with our endpoints directly. The ownership verification token method provides a token that includes information about the game client, user, and entitlement as well as a signature that can be verified by your game client or any other service. If integrating with a third-party service that performs ownership verification, it is preferred to use the ownership verification token check to avoid granting them access to a user's data.
Ownership checks walk the full tree to determine whether a user has access to a given catalogItemId. Entitlements are useful for validating specific transactions have taken place. For example, in the case of a user that purchases a Deluxe Edition of a game, which includes a Season Pass, which itself includes access to DLC1, the ownership check will return TRUE for DLC1, versus an entitlement check that will not include DLC1.
Before you start, you must integrate with the Authentication Service to obtain an access token. See the Get Started documentation on Epic Account Services for more information about authentication.
Direct Ownership Verification
The endpoint to check if a user owns an item, or a list of items.
This endpoint applies to auth tokens obtained via SDK 1.5+ or via OAuth OpenID Connect exchange implemented using configuration 'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration'
You need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following query parameters:
| Parameter | Description |
|---|---|
nsCatalogItemId | In the format of {{sandboxId:catalogItemId}}, This parameter can be repeated to check multiple sandboxId and catalogItem combinations. |
sandboxId | This parameter can be used to obtain the full list of owned catalogItemIds in a given sandbox. |
The following snippet shows a sample request to get the ownership information:
Token-based Ownership Verification
An Ownership Verification Token is a signed JWT with a five-minute expiration. It is signed using RS512 (RSA PKCS#1 signature with SHA-512, RSA key size 2048).
There are two steps to perform the token baesd ownership verification:
-
Request an ownership verification token
-
Use the public key to verify the token is genuine
Once the game client/server obtains the Ownership Verification Token, it can be passed to any integration that needs to perform ownership verification. The integration verifying the token will need to unpack the JWT to extract the kid (Key ID), then fetch the public key for that Key ID to verify the signature.
The token contains the following claims:
| Claim | Description |
|---|---|
| jti | A unique identifier for this token. |
| sub | The account ID for the account that was used to request the token. |
| clid | The client ID for the client that was used to request the token. |
| ent | An array of entitlements ownership that were verified for this token. If this value is empty, the account is not entitled to the requested entitlements |
| iat | Time when the token was issued as a Unix timestamp. |
| exp | Time when the token expires as a Unix timestamp. |
Requesting an Ownership Verification Token
To request an ownership verification token, the client will make an HTTP POST request to the ownership token endpoint.
The endpoint to request an ownership verification token is:
You will need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following request body parameters:
Note: The Content-Type needs to be "application/x-www-form-urlencoded" and the parameter needs to be in the request body.
| Parameter | Description |
|---|---|
nsCatalogItemId | In the format of {{sandboxId:catalogItemId}}, This parameter can be repeated to check multiple sandboxId and catalogItem combinations. |
The following snippet shows a sample request to get a verification token:
egoc1~ is the prefix to represent Epic Games Ownership Check. Please strip it when decoding the token.
The token includes three base64 encoded JSON objects that correspond to the JWT header, payload, and signature. Please refer to the JWT documentation for more information.
The following is a sample of the JWT header:
The following is a sample of the JWT body:
Verifying the Ownership Verification Token
To verify the signature in the token, you will need to fetch a public key. To fetch the key, you will need the Key ID (kid claim in the JWT). The response will include a JSON Web Key (JWK) that can be used to verify the signature in the JWT.
To request the Public Key, your client/service will make an HTTP request to the public keys endpoint.
The public keys endpoint is:
The following snippet shows a sample request to get a public key:
Direct Entitlement Enumeration
The endpoint to check in cases where you need to get a list of direct entitlements for accounts.
If you just need to check the ownership, please use the ownership check APIs above which is recommended by Epic.)
You will need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following query parameters:
| Parameter | Description |
|---|---|
sandboxId | The namespace for the game title. |
entitlementName | Optional. The name of the entitlement. If not provided, all entitlements under the sandboxId will be returned. This parameter can be repeated to check multiple entitlements. |
includeRedeemed | Optional. This parameter specifies whether to include entitlements that have been redeemed. This defaults to false. If not set to true, the result will only include entitlements that have NOT been redeemed. |
The following snippet shows a sample request to get all entitlements for user and sandbox:
Token-based Entitlement Verification
An Entitlement Verification Token is a JWT signed using RS512 (RSA PKCS#1 signature with SHA-512, RSA key size 2048), which expires 5 minutes after it is created.
There are two steps to perform token-based entitlement verification:
-
Request an entitlement verification token
-
Use the public key to verify the token is genuine
Once the game client/server obtains the Entitlement Verification Token, it can be passed to any integration that needs to perform ownership verification. The integration verifying the token will need to unpack the JWT to extract the kid (Key ID), then fetch the public key for that Key ID to verify the signature.
The token contains the following claims:
| Entitlement Verification Token Claims | |
|---|---|
| jti | A unique identifier for this token. |
| sub | The account ID for the account that was used to request the token. |
| clid | The client ID for the client that was used to request the token. |
| ent | An array of entitlements that were verified for this token. If this value is empty, the account is not entitled to the requested entitlement or any entitlement for the sandboxId. |
| iat | Time when the token was issued as a Unix timestamp. |
| exp | Time when the token expires as a Unix timestamp. |
Requesting an Entitlement Verification Token
To request an entitlement verification token, the client will make an HTTP POST request to the entitlement token endpoint.
The endpoint to request an entitlement verification token is https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/entitlementToken
You will need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following request parameters:
| Request Parameters | |
|---|---|
sandboxId | The namespace for the game title. |
entitlementName | (Optional) The name of the entitlement. If not provided, all entitlements under the sandboxId will be returned. This parameter can be repeated to check multiple entitlements. |
The following snippet shows a sample request to get a verification token:
Note: egoc1~ is the prefix to represent Epic Games Ownership Check. Please strip it when decoding the token
The token includes three base64 encoded JSON objects that correspond to the JWT header, payload, and signature. Please refer to the JWT documentation for more information.
The following is a sample of the JWT header:
The following is a sample of the JWT body:
Verifying the Entitlement Verification Token
To verify the signature in the token, you will need to fetch a public key. To fetch the key, you will need the Key ID (kid claim in the JWT). The response will include a JSON Web Key (JWK) that can be used to verify the signature in the JWT.
To request the Public Key, your client/service will make an HTTP request to the public keys endpoint.
The public keys endpoint is https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}
The following snippet shows a sample request to get a public key:
Query Offers
To request the list of available catalog offers for a user, the client makes an HTTP GET request to the offers endpoint.
The endpoint to request a list of catalog offers defined with Epic Online Services is shown below:
This API provides the same data as the SDK API EOS_Ecom_QueryOffers. See the EOS API Reference documentation for more information on using the SDK API.
You need to pass an access token in the Authorization header using Bearer authorization.
The following snippet shows a sample request to request offers for a user and sandbox:
The following is a sample response from the server for a virtual currency offer:
How you read the currency values in the priceInfo struct depends on the value of the decimals field. If decimals has a value of 2 (USD, CAD, Euro, etc.), then the value of the discountPrice and originalPrice fields is given in cents. So, to convert the value to whole dollar amounts, divide the amount by 100 (e.g. 350 equals 3.50 USD).
If the decimals field has a value of 0 (JPY, KRW, etc.), then the values for the other fields are exactly what they say for the specified currency. No conversion is required.
Redeem/Consume Entitlements
The endpoint to redeem/consume an entitlement. Once an entitlement is redeemed, the entitlement's status will be changed to inactive.
You need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following request body:
The following snippet shows a sample request to redeem multiple entitlements for a user and sandbox: