04. Server to Server API

Introduction

Open API provides the HTTP Interface that can call the backend service of a platform.
Game servers and web-based game clients that do not use SDK can use platform functions by using Open API.
Open API provides high-level security using HTTP Secure and an authentication key (appSecret) that is issued for each app.
It also effectively processes large volumes of traffic using its fully asynchronous internal structure.
The default timeout value is set to 5 seconds.
The read timeout for the request body is one second. If a header value is entered and the body stream does not arrive within one second, BAD_REQUEST is processed.

Version

The current version being used is v3.

Type and Precautions

Open API provides a Services API used by the game server and client and a Batch Request used only by the server.
- The Service API port is Public.
- Some Service APIs (APIs requesting authentication tokens to the header) provide their services after taking an internal authentication step.
Precautions
- A dedicated port (10443) should be used when open API is called from the game server.
- ADMIN_KEY registered in Partner Admin must be entered for the Authorization header.
  If API calling continues for 10 times or more in one minute because of a wrong Admin Key, authentication of the concerned remote IP is failed.
- The most latest value must always be used for zat, obtained through the SDK at the time of the request.
- All APIs must be called with the POST Method.

Service API

Resource URL (for Game Server)

Zone	URL

Zone	URL
Real (Live)	https://openapi-zinny3.game.kakao.com:10443/service/[version]/[api명]

Real (Live) : This means the environment of the Kakao platform, not the game server. (Must be used in game server Real(Live) Zone.)

Request Header

The Service API must contain the following items below the http header of the request.
Refer to each API for details on the header since the required and optional items differ according to API.

Request Header (for Game Server)

Key	Description	Remarks

Key	Description	Remarks
appId	Game app ID	Required for all APIs
appSecret	Secret-key issued for each game	Required for all APIs
playerId	Player ID	Required in all player-related APIs
Content-Type	Content type	Inputs application/json
Authorization	Must be used when it is used as a dedicated server for game server. Admin Key registered in Partner Admin value : KakaoAK {ADMIN_KEY}	Authorization: KakaoAK {ADMIN_KEY} (Ex) Authorization: KakaoAK c0948035a320f23423585acae3dedcd70

Request Body

The body is in the JSON format. (Note: It is not a key=value parameter.)
Please refer to each API for detailed information on the body.

Response

The Status Code is always 200, OK for successful execution, and a JSON format value is returned to the body.
Otherwise, a Status Code of 4XX or 5XX is received, and the detailed reason is contained in the desc of the body.
An example of an error is shown below. (When the profile data of an invalid user has been requested)

Refer to desc of the body if the response is a 400 Bad request. It provides a description of the omitted required parameters.

Example Request

POST /service/v3/player/getInfo HTTP/1.1
Host: openapi-zinny3.game.kakao.com
Content-Type: application/json;charset=UTF-8
appId: 103815
appSecret: 951b75bf17fe0885ab5106ba2a9f9bc9
playerId: 1824950129
  
{
    "fields": [
        "idpAlias",
        "appStatus"
    ]
}

Example Error Response

HTTP/1.1 406 Not Acceptable
Content-Type: application/json;charset=UTF-8
  
{
    "desc": "No such player (test01:1824950129)"
}