토큰 검증¶

앱 클라이언트에서 로그인 성공 후 반환된 PlayerInfo의 토큰, Player ID, Device ID를 사용하여, 앱 서버에서 해당 사용자의 토큰 유효성을 검증합니다.

토큰 검증 API는 앱 서버에서 Hive 인증 서버로 직접 호출하는 Server-to-Server 통신 방식으로 동작하며, 앱에서 중복 로그인을 허용하지 않는 경우에 한해 검증된 토큰을 관리하거나 앱 자체 세션 키를 활용한 세션 관리 기능을 구현할 수 있습니다.

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/token/get-token
분산환경 URL	https://auth.globalwithhive.com/v2/game/token/get-token
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/token/get-token
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Note

Hive 인증 서버는 장애가 발생하거나 네트워크 통신이 원활하지 않을 경우에 대비하여 분산 환경 기반으로 구성됩니다.
인증 서버 호스트와의 통신 중 장애가 발생하거나 앱 서버에 정의된 타임아웃(Timeout) 시간을 초과하는 경우, 앱 서버에서 직접 분산 환경 URL(Fallback URL)을 호출해야 합니다.

Request header¶

필드명	설명	타입	필수여부
Authorization	게임 클라이언트 로그인 성공 후 반환된 사용자 토큰 (PlayerInfo.token)	String	Y
X-Access-Token	게임 클라이언트 로그인 성공 후 반환된 User Token 플레이어 본인 인증을 위한 OAuth 2.0 Access Token	String	Y
ISCRYPT	데이터 암호화 여부 (0= 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request Body¶

필드명	설명	타입	필수여부
appid	App ID	String	Y
did	로그인 성공 후 반환된 Device ID	String	Y
player_id	로그인 성공 후 반환된 인증 Player ID	BigInteger	Y
include_fields	추가 필드 목록 응답 시 추가 정보를 요청할 필드 목록	Array	N

Note

include_fields 파라미터를 통해 선택적으로 추가 정보를 반환할 수 있습니다. 토큰 검증하기 요청 시 include_fields 배열에 명시된 필드값을 기반으로 응답의 data 하위에 해당 정보가 포함됩니다.

추가 필드 목록¶

필드명	설명	타입
is_blocked	이용 제한 여부 (`true` - 제재, `false` - 정상)	Boolean
is_device_registered	기기 관리 사용 여부 (`true` - 사용, `false` - 미사용)	Boolean
join_timestamp	`player_id` 가입일 (Unix Timestamp)	Long
china_pi_no	중국 실명 인증 번호. 실명 인증이 완료되지 않은 경우 `null` 반환	String / null

Response Body¶

필드명	설명	타입
result_code	응답 코드, 0=검증 성공	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data	요청 시 `include_fields`에 명시된 정보가 포함된 객체	Object

응답 코드¶

코드값	설명
0	성공
2300	환불 사용자 재결제 대상
4000	유효하지 않은 파라미터
4001	request json 에러
2499	JWT 검증 실패 (token_validation 참고)
5000	DB 에러
6000	유효하지 않는 appid
6001	IDP 토큰 에러
7000	유효하지 않은 토큰
7001	header에 토큰값 없음
9999	알 수 없는 오류

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "did": "255764404509548",
    "player_id": 10000000000
}

include_fields¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "did": "255764404509548",
    "player_id": 10000000000,
    "include_fields": ["is_blocked", "is_device_registered", "join_timestamp", "china_pi_no"]
}

Response example¶

성공¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    }
}

JWT 검증 실패¶

{
    "result_code": 2499,
    "result_msg": "JWT validation failed. See token_validation for details.",
    "token_validation": {
        "result_code": 2408,
        "result_msg": "The access token is expired. Please refresh your token."
    }
}

include_fields¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    },
    "data": {
        "is_blocked": false,
        "is_device_registered": false,
        "join_timestamp": 1495594605,
        "china_pi_no": null
    }
}

Note

JWT 검증 실패 시, token_validation 필드로 상세 에러 정보를 확인할 수 있습니다. 자세한 내용은 JWT 검증 에러 코드를 참고하세요.