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 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 getting started, you must integrate with the Authentication Service to obtain an access token. Review Getting started with Epic Account Servicesfor more information about authentication.
Online Ownership Verification
The endpoint to check if a user owns an item, or a list of items.
https://api.epicgames.dev/epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownership?nsCatalogItemId={{sandboxId:catalogItemId}}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 |
|---|---|
|
|
In the format of |
The following snippet shows a sample request to get the ownership information:
GET /epic/ecom/v1/platforms/EPIC/identities/94edb6df476d45199f6be940aa1337c0/ownership HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
nsCatalogItemId=fn:ff150af93c9a4fb99fee12f5db49fa5b&nsCatalogItemId=fn:94egdb6df476d45199f6be940aa1337c0
[
{
"namespace": "fn",
"itemId": "94egdb6df476d45199f6be940aa1337c0",
"owned": false
},
{
"namespace": "fn",
"itemId": "ff150af93c9a4fb99fee12f5db49fa5b",
"owned": true
}
]Ownership Verification Token
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 offline 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 the token was issued as a Unix timestamp. |
|
exp |
Time 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:
https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/ownershipTokenYou 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 |
|---|---|
|
|
In the format of |
The following snippet shows a sample request to get a verification token:
POST /epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownershipToken HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
nsCatalogItemId=fn:c204662afac64acd8a2117590be477da
{
"token": "egoc1~eyJraWQiOiJWbWdpMDFoQ2V2dXVEbUtWZFZubXphWnhpT2lBa0dEZWdRQmdDdWc4dkRZIiwiYWxnIjoiUlM1MTIifQ.eyJzdWIiOiI5NGVkYjZkZjQ3NmQ0NTE5OWY2YmU5NDBhYTEzMzdjMCIsImlwIjoiNTAuOTguMjI2LjEwIiwiY2xpZCI6IjI5Y2VlNDJlNzExNzQ2ZTFiYmNhZmI2MjkyOWU0OGZkIiwiZW50IjpbeyJjYXRhbG9nSXRlbUlkIjoiYzIwNDY2MmFmYWM2NGFjZDhhMjExNzU5MGJlNDc3ZGEiLCJvd25lZCI6dHJ1ZSwibmFtZXNwYWNlIjoiY2F0bmlwIn1dLCJleHAiOjE1Njk5Nzg1NjUsImlhdCI6MTU2OTk3ODI2NSwianRpIjoiMzgzN2FjODhlNDJjNDE1OTlmMzI5OTNjMmViYzBhOWQifQ.CX4yEEsZph9qPaVvtpnS0sLe_9YGLic5jIOQhhk3tG88GfNLp10w5y9DbYXocDlMXdEoAsAt-33G1JOPIFzrktrOxpR_FNdQ_ozCbBCF1aTQFTYKtvrbYkpA5AIGHmy_J9jSKMq-jN4TQxoSbR0LnowiWoKp_ntibmx0titFQ0kOYBQMvwwTlLgTzUv55I6VlFl8gMBSEw1_oRIUbdNbdHJO4UwnHTeUbcUUvuAWm13BpI2P39vRjU1xx4t51kUj_yY9ISWFBSGsLgEAhH13Mm1CilaeiPsLanE1sA5B3mRMjq8KcLtkkp8JvlIrgD4e-xo_tnRSLkRyKuU0GoqNKw"
}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:
{
"kid": "tFC2UIhFpTM_Ea3qcOd_MqQT1cBBm9kFLSDfeJhsRG8",
"alg": "RS512"
}The following is a sample of the JWT body:
{
"jti" : "a19c3f03edf84c0a9621ee44ff36566f",
"sub" : "d144285abee343df98c4e84572c576bb",
"clid": "44c39619da304266855c9646e1081ab5",
"iat" : 1547675438,
"exp" : 1547704238,
"ent" : [{
"catalogItemId": "c204662afac64acd8a2117590be477da",
"owned": true,
"namespace": "catnip"
}]
}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:
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:
GET /ecommerceintegration/api/public/publickeys/Vmgi01hCevuuDmKVdVnmzaZxiOiAkGDegQBgCug8vDY HTTP/1.1
Host: ecommerceintegration-public-service-ecomprod02.ol.epicgames.com
{
"kty": "RSA",
"e": "AQAB",
"kid": "Vmgi01hCevuuDmKVdVnmzaZxiOiAkGDegQBgCug8vDY",
"n": "k-LHmLHW5bbiqYLmPxC77ciG4N7IuF1SUOSsnDBLneKH3ZAU9kXRkq5MYjmRjxt8g3HpXmmhi_sHe4_g-VnSrM7jP6ntMiJ5t0d5J9ERkSEUSY4w_LS_YECavTr76GiutV_xPT-9jpHJWdVYqk68tiqR42xPFHEFUkYYsb_t6gONhth85ICnVY8Mjg6F0hFvvaMvOJcDVYfQbdjWY8-mzvIF9DmvyVkWaZSQYBaVuNCNKkSiSnkyCtbrynneayugwW0R-rNP5lEcp8UwXpBnep6sRf8nQEsByCnR91RdRXjuvrCSl7fOxpFX82t2WjWTYEOkOgb6yGc_ft-sJidSIQ"
}Entitlement Enumeration
The endpoint to check in cases where you need to get a list of direct entitlements for accounts.
https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlementsIf 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 |
|---|---|
|
|
The namespace for the game title. |
|
|
|
The following snippet shows a sample request to get all entitlements for user and sandbox:
GET /api.epicgames.dev/epic/ecom/v1/identities/94edb6df476d45199f6be940aa1337c0/entitlements HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
[{
"id": "8894469f1120432095eff043a4529433",
"entitlementName": "942e8a7133464f0ea83179030536505e",
"namespace": "buffalo",
"catalogItemId": "942e8a7133464f0ea83179030536505e",
"accountId": "94edb6df476d45199f6be940aa1337c0",
"identityId": "94edb6df476d45199f6be940aa1337c0",
"entitlementType": "AUDIENCE",
"grantDate": "2019-01-04T21:34:24.826Z",
"consumable": false,
"status": "ACTIVE",
"active": true,
"useCount": 0,
"originalUseCount": 0,
"entitlementSource": "AppEpicgamesCom",
"platformType": "EPIC",
"created": "2019-01-04T21:34:24.829Z",
"updated": "2019-01-04T21:34:24.829Z",
"groupEntitlement": false
},
{
"id": "e21aa0b339ae4e778971058c9395b2b7",
"entitlementName": "25ed76af7816430cbfc0f5e6d3195d56",
"namespace": "badger",
"catalogItemId": "25ed76af7816430cbfc0f5e6d3195d56",
"identityId": "94edb6df476d45199f6be940aa1337c0",
"entitlementType": "AUDIENCE",
"grantDate": "2019-01-16T04:42:06.270Z",
"consumable": false,
"status": "ACTIVE",
"useCount": 0,
"originalUseCount": 0,
"entitlementSource": "LauncherWeb",
"platformType": "EPIC",
"created": "2019-01-16T04:42:06.273Z",
"updated": "2019-01-16T04:42:06.273Z",
"groupEntitlement": false,
"country": "CA"
}]Redeem/Consume Entitlements
The endpoint to redeem/consume an entitlement. Once an entitlement is redeemed, the entitlement's status will be changed to inactive.
https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlements/redeemYou need to pass an access token in the Authorization header using Bearer authorization.
This endpoint supports the following request body:
{
"entitlementIds": [
"8894469f1134432095eff043a4529433",
"25ed76af9816430cbfc0f5e6d3195d56"
],
"sandboxId": "8894469f1120432095eff043a4529433"
}The following snippet shows a sample request to redeem multiple entitlements for a user and sandbox:
PUT
/ecom/v1/identities/94edb6df476d45199f6be940aa1337c0/entitlements/redeem
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
Content-Type: application/json
Request body:
{
"entitlementIds": [
"8894469f1134432095eff043a4529433",
"25ed76af9816430cbfc0f5e6d3195d56"
],
"sandboxId": "8894469f1120432095eff043a4529433"
}