Ecom Web APIs

SDK를 사용하지 않고 오너십을 검증하는 RESTful 엔드포인트입니다.

Epic Games Store
10 분 소요

에픽 온라인 서비스 (EOS)는 카탈로그 아이템의 계정 오너십을 검증하는 다양한 방법을 제공합니다. 선호되는 방법은 Ecom 인터페이스를 통한 EOS SDK API를 사용하는 것입니다. 이 문서는 RESTful 엔드포인트를 통해 오너십 정보에 액세스하는 것을 선호하는 게임과 서비스를 위해 제공된 문서입니다. EOS에는 RESTful 서비스 엔드포인트가 있어 클라이언트와 서비스 간에 전달 가능한 소유권 토큰을 생성하고 검증하는 직접 온라인 오너십 검증이 가능하며 권한 기록을 열거하고 소비하는 권한 서비스를 제공합니다.

오너십 확인에 사용되는 메서드는 사용 사례에 따라 다릅니다. 에픽게임즈 엔드포인트와 직접 통합하여 게임 클라이언트나 게임 서버에서 온라인 메서드를 사용할 수 있습니다. 오너십 검증 토큰 메서드는 게임 클라이언트와 사용자, 권한 관련 정보는 물론 게임 클라이언트 또는 여타 서비스를 통해 확인될 수 있는 서명 정보가 포함된 토큰을 제공합니다. 오너십을 검증하는 타사 서비스와 통합하려는 경우에는 오너십 검증 토큰 확인을 사용하여 타사 서비스가 사용자 데이터에 액세스하지 못하게 하는 방법이 선호됩니다.

오너십 확인은 전체 트리를 탐색하여 사용자가 지정된 catalogItemId에 액세스할 수 있는지 결정합니다. 권한은 특정한 트랜잭션이 발생했는지 검증하는 데 유용합니다. 예를 들어, 시즌 패스가 포함된 게임의 디럭스 에디션을 구매한 사용자의 경우 시즌 패스에 DLC1 액세스 권한이 포함되므로 DLC1의 오너십을 확인하는 경우 TRUE를 반환하는 반면, 권한 확인을 진행하는 경우 DLC1는 포함되지 않기 때문입니다..

시작하기 전에 반드시 인증 서비스(Authentication Service)를 통합하여 액세스 토큰을 얻어야 합니다. 인증에 대한 자세한 정보는 에픽 계정 서비스 시작하기를 참조하세요.

직접 오너십 검증

사용자가 아이템이나 아이템 목록을 소유하고 있는지 확인하는 엔드포인트입니다.

https://api.epicgames.dev/epic/ecom/v1/platforms/EPIC/identities/{{currentAccountId}}/ownership?nsCatalogItemId={{sandboxId:catalogItemId}}

이 엔드포인트는 SDK 1.5+를 통해 얻거나 'https://api.epicgames.dev/epic/oauth/v1/.well-known/openid-configuration' 환경설정을 사용하여 구현된 OAuth OpenID Connect 교환으로 얻은 인증 토큰에 적용됩니다.

Bearer 인증을 사용하여 인증 헤더에 액세스 토큰을 전달해야 합니다.

이 엔드포인트는 다음과 같은 쿼리 파라미터를 지원합니다.

파라미터설명
nsCatalogItemId이 파라미터는 {{sandboxId : catalogItemId}} 형식으로, sandboxId와 catalogItem의 여러 조합을 반복해서 확인할 수 있습니다.
sandboxId이 파라미터는 특정 샌드박스에서 소유된 catalogItemIds 의 전체 리스트를 얻는 데 사용될 수 있습니다.

다음은 오너십 정보를 획득하기 위한 요청 샘플을 보여주는 코드 조각입니다.

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
}
]

토큰 기반 오너십 검증

오너십 검증 토큰은 서명된 JWT로, 만료 기간은 5분입니다. 이는 RS512(SHA-512를 사용한 RSA PKCS#1 서명, RSA 키 크기 2048)를 사용하여 서명됩니다.

토큰 기반 오너십 검증은 다음과 같이 2단계로 진행됩니다.

  1. 오너십 검증 토큰 요청

  2. 공개 키를 사용하여 토큰의 진위 검증

게임 클라이언트나 서버가 오너십 검증 토큰을 획득하면, 오너십 검증을 수행해야 하는 통합으로 전달될 수 있습니다. 토큰을 검증하는 통합은 JWT의 압축을 풀고 키 ID(kid)를 추출한 다음, 해당 키 ID를 위한 공개 키를 가져와 서명을 검증해야 합니다.

토큰에는 다음과 같은 클레임이 포함됩니다.

클레임설명
jti이 토큰의 고유 식별자입니다.
sub토큰을 요청하는 데 사용된 계정의 계정 ID입니다.
clid토큰을 요청하는 데 사용된 클라이언트의 클라이언트 ID입니다.
ent이 토큰에 검증된 일련의 권한 오너십입니다. 이 값이 비어 있으면 요청된 권한이 계정에 부여되지 않습니다.
iat토큰이 발급된 시간을 나타내는 Unix 타임 스탬프입니다.
exp토큰이 만료된 시간을 나타내는 Unix 타임 스탬프입니다.

오너십 검증 토큰 요청하기

오너십 검증 토큰을 요청하려면 클라이언트는 오너십 엔드포인트에 HTTP POST 요청을 해야 합니다.

오너십 검증 토큰을 요청하는 엔드포인트는 다음과 같습니다.

https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/ownershipToken

Bearer 인증을 사용하여 인증 헤더에 액세스 토큰을 전달해야 합니다.

이 엔드포인트는 다음과 같은 요청 본문 파라미터를 지원합니다.

참고: Content-Type은 "application/x-www-form-urlencoded "여야 하며, 파라미터는 요청 본문에 있어야 합니다.

파라미터설명
nsCatalogItemId이 파라미터는 {{sandboxId : catalogItemId}} 형식으로, sandboxId와 catalogItem의 여러 조합을 반복해서 확인할 수 있습니다.

다음은 검증 토큰을 획득하기 위한 요청 샘플을 보여주는 코드 조각입니다.

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~ 은 에픽게임즈 오너십 확인을 나타내는 접두사입니다. 토큰 디코딩 시 이 접두사를 제거해 주세요.

토큰에는 JWT 헤더와 페이로드, 서명에 해당하는 base64로 인코딩된 JSON 오브젝트 3개가 포함됩니다. 자세한 내용은 JWT 문서를 참조하세요.

다음은 JWT 헤더 샘플입니다.

{
"kid": "tFC2UIhFpTM_Ea3qcOd_MqQT1cBBm9kFLSDfeJhsRG8",
"alg": "RS512"
}

다음은 JWT 본문 샘플입니다.

{
"jti" : "a19c3f03edf84c0a9621ee44ff36566f",
"sub" : "d144285abee343df98c4e84572c576bb",
"clid": "44c39619da304266855c9646e1081ab5",
"iat" : 1547675438,
"exp" : 1547704238,
"ent" : [{
"catalogItemId": "c204662afac64acd8a2117590be477da",
"owned": true,
"namespace": "catnip"
}]
}

오너십 검증 토큰 검증하기

토큰 내 서명을 검증하려면 공개 키를 가져와야 합니다. 키를 가져오려면 키 ID(JWT 내의 kid 클레임)가 필요합니다. 응답에는 JWT에서 서명 검증에 사용될 수 있는 JSON 웹 키(JWK)가 포함됩니다.

공개 키를 요청하려면 클라이언트나 서비스가 공개 키 엔드포인트로 HTTP 요청을 보내야 합니다.

공개 키 엔드포인트는 다음과 같습니다.

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

다음은 공개 키를 획득하기 위한 요청 샘플을 보여주는 코드 조각입니다.

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"
}

직접 권한 열거

계정에 대한 직접 권한 목록을 획득해야 할 때 확인하는 엔드포인트입니다.

https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlements

오너십만 확인해야 하는 경우에는 위에 있는 에픽에서 권장하는 오너십 확인 API를 사용해 주세요.

Bearer 인증을 사용하여 인증 헤더에 액세스 토큰을 전달해야 합니다.

이 엔드포인트는 다음과 같은 쿼리 파라미터를 지원합니다.

파라미터설명
sandboxId게임 타이틀의 네임스페이스입니다.
entitlementName선택 항목입니다. 권한 이름입니다. 제공되지 않은 경우, 해당 sandboxId의 모든 권한이 반환됩니다. 이 파라미터는 여러 권한을 반복해서 확인할 수 있습니다.

다음은 사용자 및 샌드박스를 위해 모든 권한을 얻기 위한 요청 샘플을 보여주는 코드 조각입니다.

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",
"entitlementType": "AUDIENCE",
"grantDate": "2019-01-04T21:34:24.826Z",
"consumable": false,
"status": "ACTIVE",
"useCount": 0,
"entitlementSource": "AppEpicgamesCom"
},
{
"id": "e21aa0b339ae4e778971058c9395b2b7",
"entitlementName": "25ed76af7816430cbfc0f5e6d3195d56",
"namespace": "badger",
"catalogItemId": "25ed76af7816430cbfc0f5e6d3195d56",
"entitlementType": "AUDIENCE",
"grantDate": "2019-01-16T04:42:06.270Z",
"consumable": false,
"status": "ACTIVE",
"useCount": 0,
"entitlementSource": "LauncherWeb"
}]

토큰 기반 권한 검증

권한 검증 토큰(Entitlement Verification Token)은 RS512(SHA-512를 사용한 RSA PKCS#1 서명, RSA 키 크기 2048)를 사용하여 서명한 JWT로, 생성 후 5분이 지나면 만료됩니다.

토큰 기반 권한 검증은 다음과 같이 2단계로 진행됩니다.

  1. 권한 검증 토큰 요청

  2. 공개 키를 사용하여 토큰의 진위 검증

게임 클라이언트나 서버가 권한 검증 토큰을 획득하면, 오너십을 검증해야 하는 통합에 전달할 수 있습니다. 토큰을 검증하는 통합은 JWT의 압축을 풀고 키 ID(kid)를 추출한 다음, 해당 키 ID를 위한 공개 키를 가져와 서명을 검증해야 합니다.

토큰에는 다음과 같은 클레임이 포함됩니다.

권한 검증 토큰 클레임
jti이 토큰의 고유 식별자입니다.
sub토큰을 요청하는 데 사용된 계정의 계정 ID입니다.
clid토큰을 요청하는 데 사용된 클라이언트의 클라이언트 ID입니다.
ent이 토큰에 검증된 일련의 권한입니다. 이 값이 비어 있으면 요청된 권한 또는 sandboxId에 대한 권한이 계정에 부여되지 않습니다.
iat토큰이 발급된 시간을 나타내는 Unix 타임 스탬프입니다.
exp토큰이 만료된 시간을 나타내는 Unix 타임 스탬프입니다.

Requesting an Entitlement Verification Token

권한 검증 토큰 요청하기

권한 검증 토큰을 요청하려면 클라이언트는 권한 토큰 엔드포인트에 HTTP POST 요청을 해야 합니다.

권한 검증 토큰을 요청하는 엔드포인트는 https://api.epicgames.dev/epic/ecom/v1/platforms/{platform}/identities/{identityId}/entitlementToken입니다.

Bearer 인증을 사용하여 인증 헤더에 액세스 토큰을 전달해야 합니다.

이 엔드포인트는 다음과 같은 요청 파라미터를 지원합니다.

요청 파라미터
sandboxId게임 타이틀의 네임스페이스입니다.
entitlementName(옵션) 권한 이름입니다. 제공되지 않은 경우, 해당 sandboxId의 모든 권한이 반환됩니다. 이 파라미터는 여러 권한을 반복해서 확인할 수 있습니다.

다음은 검증 토큰을 획득하기 위한 요청 샘플을 보여주는 코드 조각입니다.

POST
/epic/ecom/v1/platforms/EPIC/identities/94edb6df476d45199f6be940aa1337c0/entitlementToken HTTP/1.1
Host: api.epicgames.dev
Authorization: Bearer 1fe59d629cda497b9f65dbdbee7d468e
sandboxId=2bd59d629cda497b9f65dbdbee7d443s
{
"token": "egoc1~eyJraWQiOiJ0RkMyVUloRnBUTV9FYTNxY09kX01xUVQxY0JCbTlrRkxTRGZlSmhzUkc4IiwiYWxnIjoiUlM1MTIifQ. eyJqdGkiOiJhMTljM2YwM2VkZjg0YzBhOTYyMWVlNDRmZjM2NTY2ZiIsInN1YiI6ImQxNDQyODVhYmVlMzQzZGY5OGM0ZTg0NTcyYzU3NmJiIiwiY2xpZCI6IjQ0YzM5NjE5ZGEzMDQyNjY4NTVjOTY0NmUxMDgxYWI1IiwiaWF0IjoxNTQ3Njc1NDM4LCJleHAiOjE1NDc3MDQyMzgsImVudCI6W3siaWF0IjoxNTQ3Njc1MDAwLCJuYmYiOjE1NDc2NzkwMDAsInNyYyI6IkVQSUMiLCJucyI6InNuYXBkcmFnb24iLCJpdGVtIjoiMTJmYjdkNTBiYmJhNGQwNTlkNWJhYzJlOGUyNzZkMmYiLCJ0eXBlIjoiRU5USVRMRU1FTlQiLCJuYW1lIjoiNDNlZDI4ZTU3N2FiNGMyYThjZWEyN2Q2YjQ0YmJhMTgiLCJjb25zIjoxLCJ1c2NudCI6MH1dfQ.JHFFCjxmcKQDBGWaas53PsvaqeobK_kLZDgw3Je9Btwx5AzmmnW8TGUQGgr-FdZEkpdP2N_TMYV2UBO91QG1ApvwCYrvW3IYBwtl3_9e3NA1QrNLqw2qxG9X8LPiowh0gRO7rpJJ4BwbrYBwImcyf0KPhmCEKkHI9XiDsZDkoD8"
}

참고: egoc1~은 에픽게임즈 오너십 확인(Epic Games Ownership Check)을 나타내는 접두사입니다. 토큰 디코딩 시 이 접두사를 제거해 주세요.

토큰에는 JWT 헤더와 페이로드, 서명에 해당하는 base64로 인코딩된 JSON 오브젝트 3개가 포함됩니다. 자세한 내용은 JWT 문서를 참조하세요.

다음은 JWT 헤더 샘플입니다.

{
"kid": "tFC2UIhFpTM_Ea3qcOd_MqQT1cBBm9kFLSDfeJhsRG8",
"alg": "RS512"
}

다음은 JWT 본문 샘플입니다.

{
"jti" : "a19c3f03edf84c0a9621ee44ff36566f",
"sub" : "d144285abee343df98c4e84572c576bb",
"clid": "44c39619da304266855c9646e1081ab5",
"iat" : 1547675438,
"exp" : 1547704238,
"ent" : [{
"grantDate" : 1547375000,
"startDate" : 1547375000,
"endDate" : (timestamp, optional),
"platformType" : "EPIC",
"namespace" : "tbd",
"catalogItemId" : "tbd",
"entitlementType" : "AUDIENCE",
"entitlementName" : "43ed28e577ab4c2a8cea27d6b44bba18",
"consumable" : false,
"useCount" : 0
}]
}

권한 검증 토큰 검증하기

토큰 내 서명을 검증하려면 공개 키를 가져와야 합니다. 키를 가져오려면 키 ID(JWT 내의 kid 클레임)가 필요합니다. 응답에는 JWT에서 서명 검증에 사용될 수 JSON 웹 키(JWK)가 포함됩니다.

공개 키를 요청하려면 클라이언트나 서비스가 공개 키 엔드포인트로 HTTP 요청을 보내야 합니다.

공개 키 엔드포인트는 https://ecommerceintegration-public-service-ecomprod02.ol.epicgames.com/ecommerceintegration/api/public/publickeys/{kid}입니다.

다음은 공개 키를 획득하기 위한 요청 샘플을 보여주는 코드 조각입니다.

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"
}

권한 등록/소모

권한을 등록하거나 소모하는 엔드포인트입니다. 권한이 등록되면 권한 상태가 비활성으로 변경됩니다.

https://api.epicgames.dev/epic/ecom/v1/identities/{identityId}/entitlements/redeem

Bearer 인증을 사용하여 인증 헤더에 액세스 토큰을 전달해야 합니다.

이 엔드포인트는 다음과 같은 요청 본문을 지원합니다.

{
"entitlementIds": [
"8894469f1134432095eff043a4529433",
"25ed76af9816430cbfc0f5e6d3195d56"
],
"sandboxId": "8894469f1120432095eff043a4529433"
}

다음은 사용자 및 샌드박스의 여러 권한을 등록하기 위한 요청 샘플을 보여주는 코드 조각입니다.

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"
}