Connect Web APIs

연결 인터페이스 웹 API를 사용하여 EOS 게임 서비스 웹 API로 인증합니다.

7 분 소요

웹 API(Web API)를 통해 EOS 게임 서비스에 액세스할 수 있습니다. 웹 API는 요청한 인증된 클라이언트를 식별하기 위해 액세스 토큰을 요구합니다. 클라이언트는 독립 클라이언트(클라이언트 액세스 토큰)로서 혹은 사용자를 대신하여(사용자 액세스 토큰) 액세스 토큰을 요청할 수 있습니다.

예를 들어, 웹 애플리케이션은 계정 연결 관리 기능을 플레이어에게 제공하기 위해 사용자를 인증할 수 있습니다. 독립 클라이언트는 EOS 보이스 백엔드 서비스에서 호스팅하는 음성 채팅방을 조직하는 퍼블리셔 호스팅 백엔드일 수 있습니다.

EOS 액세스 토큰 요청하기

EOS 연결 백엔드는 OAuth 2.0 토큰 엔드포인트를 제공하여 EOS 게임 서비스 웹 API용 액세스 토큰을 요청할 수 있습니다.

EOS 연결 토큰 엔드포인트는 다음과 같습니다.

https://api.epicgames.dev/auth/v1/oauth/token

클라이언트는 다음 두 가지 유형의 액세스 토큰을 요청할 수 있습니다.

  • 클라이언트 액세스 토큰: 독립 클라이언트가 일반 제품 수준 액세스를 제공하기 위해 백엔드 서비스와 인터랙션하는 데 사용됩니다.
  • 사용자 액세스 토큰: 클라이언트가 인증된 사용자를 대신하여 백엔드 서비스와 인터랙션하는 데 사용됩니다.

클라이언트가 액세스 토큰을 요청할 때에는 제품에 유효한 클라이언트 크리덴셜 세트를 제공해야 합니다. 제품 세팅개발자 포털에서 각 제품에 클라이언트를 생성하고 개별 클라이언트 정책을 수신할 수 있습니다.

클라이언트는 다음 두 가지 방법 중 하나로 클라이언트 크리덴셜을 전달할 수 있습니다.

  • 표준 인증 HTTP 헤더 사용 또는
  • POST 파라미터 사용

토큰 요청

HTTP 메서드 POST /auth/v1/oauth/token

HTTP 헤더

이름
AuthorizationBasic <Base64(ClientId:ClientSecret)>. 예시: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Typeapplication/x-www-form-urlencoded

POST 본문 파라미터

이름
grant_type클라이언트 액세스의 경우 client_credentials 를 사용합니다. 사용자 액세스의 경우 external_auth 를 사용합니다.
client_id 클라이언트 크리덴셜 ID입니다. 인증 HTTP 헤더를 사용하지 않는 경우에 필요합니다.
client_secret클라이언트 크리덴셜 암호입니다. 인증 HTTP 헤더를 사용하지 않는 경우에 필요합니다.
nonce클라이언트가 제공한 임의의 스트링 값으로, 보안을 강화합니다. 클라이언트를 위한 API 응답에 포함되어 난스(nonce) 값이 올바른지 검증합니다. 사용자 액세스에 필요합니다.
deployment_id사용자 액세스에 필요한 필수(Required) 액세스를 요청하는 타깃 EOS 디플로이입니다.
external_auth_token외부 계정 시스템에서 사용자 계정을 식별하는 외부 인증 토큰입니다. 사용자 액세스에 필요합니다.
external_auth_type외부 인증 토큰의 유형을 식별합니다. 사용자 액세스에 필요합니다. 가능한 값은 다음과 같습니다. amazon_access_token , apple_id_token , discord_access_token , epicgames_access_token , epicgames_id_token , gog_encrypted_sessionticket , google_id_token , itchio_jwt , itchio_key , nintendo_id_token , oculus_userid_nonce , openid_access_token , psn_id_token , steam_access_token , steam_encrypted_appticket , xbl_xsts_token

요청 예시

curl -X "POST" "https://api.epicgames.dev/auth/v1/oauth/token" \ -H "Content-Type:application/x-www-form-urlencoded" \ -H "Accept:application/json" \ -H "Authorization: Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0" \ -d "grant_type=client_credentials&deployment_id=<deploymentId>"

토큰 응답

HTTP 200 - OK

HTTP 헤더

이름
Content-Typeapplication/json

JSON 페이로드

이름설명
Access_tokenJSON 웹 토큰(JWT) 스트링으로 생성된 액세스 토큰입니다. 이 액세스 토큰은 인증된 클라이언트와 사용자를 설명합니다.
token_type항상 bearer 로 설정됩니다.
expires_at토큰 유효 기간입니다. NumericDate 숫자 값을 포함하며, 유닉스 시간(Unix epoch)으로부터 시간 지점을 초 단위로 나타냅니다.
expires_in토큰 수명입니다. 토큰의 발행 시간부터 만료 시간까지를 초 단위로 나타냅니다.
nonce클라이언트가 토큰 요청에 제공하는 임의의 스트링 값입니다. 보안 강화를 위해 클라이언트가 사용합니다. HTTP 응답으로 액세스 토큰을 수신할 때, 클라이언트가 토큰 응답에 예상 난스 값이 포함되어 있는지 검증할 수 있습니다.
organization_id조직 ID입니다.
product_id 제품 ID입니다.
sandbox_id샌드박스 ID입니다.
deployment_id디플로이 ID입니다.
features클라이언트에게 액세스가 허용된 기능 목록입니다. 개발자 포털에서 클라이언트에게 기능 액세스를 허용할 수 있습니다.
organization_user_id조직 내 제품들에서 EOS 사용자를 고유하게 식별합니다. 사용자 액세스 토큰에 포함됩니다.
product_user_id인증된 EOS 제품 사용자 ID입니다. 사용자 액세스 토큰에 포함됩니다.
id_tokenEOS 제품 사용자를 안전하게 식별하는 ID 토큰입니다. 사용자 액세스 토큰에 포함됩니다.

수신한 access_token 은 인증 HTTP 헤더에 Bearer 토큰으로 제공되어 EOS 게임 서비스 웹 API를 호출하는 데 사용됩니다. 예시: Authorization: Bearer <access_token> .

응답 예시

{
"access_token" : "<Access Token>",
"token_type" : "bearer",
"expires_at" : "2021-06-11T23:10:53.491Z",
"expires_in" : 3599,
"features" : ["Matchmaking", "Voice"],
"organization_id" : "<Organization ID>",
"product_id" : "<Product ID>",
"sandbox_id" : "<Sandbox ID>",
"deployment_id" : "<Deployment ID>"
}

외부 계정 쿼리

queryExternalAccountsForAnyUser 요청은 외부 계정 ID 목록에서 관련 제품 사용자 ID를 반환합니다.

정책

클라이언트에서는 연결 기능의 queryExternalAccountsForAnyUser 클라이언트 정책 액션을 활성화해야 합니다.

인증

이 호출에는 EOS 클라이언트 액세스 토큰을 통한 Bearer 토큰 인증이 필요합니다.

QueryExternalAccounts 요청

HTTP 요청

GET /user/v1/accounts

HTTP 헤더

이름
AuthorizationBearer <EOS client access token>

HTTP 쿼리 파라미터

이름유형설명
accountId배열 <String>제품 사용자 ID를 쿼리할 외부 계정 ID의 목록입니다. 최대 입력 계정 ID 수는 16개입니다.
identityProviderId스트링지원되는 ID 제공자입니다. 다음과 같은 값을 사용할 수 있습니다. Amazon , apple , discord , epicgames , gog , google , itchio , nintendo , oculus , Openid , psn , steam , xbl
environment스트링외부 계정 시스템이 분리된 계정 환경을 사용하는 경우 반드시 환경을 지정해야 합니다. 플랫폼 사업자의 문서에서 사용 가능한 환경 값을 확인하세요. 이렇게 분리된 계정 환경을 사용하지 않는 경우에는 이 필드를 제외해야만 합니다.

요청 예시

curl -X "GET" "https://api.epicgames.dev/user/v1/accounts?accountId=<ExternalAccountId_1>&accountId=<ExternalAccountId_2>&identityProviderId=<IdentityProviderId>" \ -H "Accept:application/json" \ -H "Authorization: Bearer <EOS client access token>"

QueryExternalAccounts 응답

HTTP Response 200 - OK: 성공.

HTTP 헤더

이름
Content-Typeapplication/json

JSON 페이로드

이름유형설명
ids오브젝트 <String, String> 키는 외부 계정 ID입니다. 값은 제품 사용자 ID입니다.외부 계정 ID를 제품 사용자 ID에 매핑하는 오브젝트입니다. 외부 계정 ID가 제품 사용자 ID와 연관되지 않은 경우 응답에서 제외됩니다.

응답 예시

{
"ids": {
"<ExternalAccountId_1>": "<ProductUserId_1>",
"<ExternalAccountId_2>": "<ProductUserId_2>",
}
}

제품 사용자 쿼리

The request queryProductUsersForAnyUser 요청은 제품 사용자 ID 목록에서 연관된 계정을 반환합니다.

정책

클라이언트에서는 연결 기능의 queryProductUsersForAnyUser 클라이언트 정책 액션을 활성화해야 합니다.

인증

이 호출에는 EOS 클라이언트 액세스 토큰을 통한 Bearer 토큰 인증이 필요합니다.

QueryProductUsers 요청

HTTP 요청 GET /user/v1/product-users
HTTP 헤더
이름
Authorization Bearer <EOS client access token>
HTTP 쿼리 파라미터
이름 유형 설명
productUserId 배열 <String> 계정을 쿼리할 제품 사용자 ID의 목록입니다. 최대 입력 제품 사용자 ID 수는 16개입니다.

요청 예시

curl -X "GET" "https://api.epicgames.dev/user/v1/product-users?productUserId=<ProductUserId_1>&productUserId=<ProductUserId_2>" \
-H "Accept:application/json" \
-H "Authorization: Bearer <EOS client access token>"

QueryProductUsers 응답

HTTP Response 200 - OK: 성공.
HTTP 헤더
이름
Content-Type application/json
JSON 페이로드
이름 유형 설명
productUsers 오브젝트 <String, ProductUser> 키는 제품 사용자 ID입니다. 제품 사용자 ID를 계정에 매핑하는 오브젝트입니다. 제품 사용자 ID를 찾지 못한 경우 응답에서 제외됩니다.

스키마(Schema)

ProductUser
이름 유형 설명
accounts 배열<Account> 제품 사용자와 연결된 계정입니다.
계정
이름 유형 설명
accountId 스트링 외부 계정 ID입니다.
identityProviderId 스트링

외부 계정의 ID 제공자입니다. 지원되는 제공자는 다음과 같습니다.

  • amazon
  • apple
  • discord
  • epicgames
  • gog
  • google
  • itchio
  • nintendo
  • oculus
  • openid
  • psn
  • steam
  • xbl

신규 ID 제공자가 목록에 추가될 수도 있습니다.

displayName 스트링(옵션) 사용자 표시명입니다.
lastLogin 스트링 마지막 로그인 시간입니다(ISO 8601 형식).

응답 예시

{
"productUsers": {
"<ProductUserId_1>": {
"accounts": [
{
"accountId": "<AccountId_1>",
"displayName": "<DisplayName_1>",
"identityProviderId": "<IdentityProvider_1>",
"lastLogin": "2022-03-18T11:55:44Z"
}
]
},
"<ProductUserId_2>": {
"accounts": [
{
"accountId": "<AccountId_2>",
"displayName": "<DisplayName_2>",
"identityProviderId": "<IdentityProvider_2>",
"lastLogin": "2022-01-05T10:25:38Z"
}
]
}
}
}