IdP 계정 관리¶

IdP(Identity Provider) 자격 증명 정보를 활용하여 플레이어 계정을 생성하고 관리합니다.

'IdP 계정 관리' API는 앱 서버에서 Hive 인증 서버로 직접 호출하는 Server-to-Server 통신 방식으로 동작하며, Player ID 생성, 로그인, IdP 연동 및 해제 처리뿐만 아니라, 웹 환경에서의 로그인 구현, 기존 계정 마이그레이션 등 다양한 용도로 활용할 수 있습니다.

Note

Google, Meta, Apple 등 외부 인증 제공자를 통한 사용자 인증 및 자격 증명 획득 절차는 본 API에서 지원하지 않으며, 앱 클라이언트에서 직접 구현하여 앱 서버로 전달합니다.

'IdP 계정 관리' 기능으로 제공되는 API는 아래와 같습니다.

API Endpoint	설명
`POST /v2/game/auth/signinidp`	IdP 로그인
`POST /v2/game/auth/connect`	IdP 연동
`POST /v2/game/auth/disconnect`	IdP 연동 해제

IdP 로그인¶

IdP 정보로 신규 플레이어의 Player ID를 생성하거나, 이미 등록된 IdP인 경우 기존 플레이어 정보를 반환합니다. IdP 로그인 요청 성공 시 data.player_id로 생성된 Player ID를 확인할 수 있습니다.

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/signinidp
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/signinidp
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
idp_index	IdP 인덱스 코드. IdP 인덱스 참조 참고	Integer	Y
idp_user_id	IdP 사용자 고유 식별자	String	Y
require_token	플레이어 토큰 요청 여부. 계정 삭제 API 사용 시 `true`, 미사용 시 `false`	Boolean	Y

Note

계정 삭제 API를 사용하려면 require_token을 true로 설정하여 응답 헤더의 Authorization 값을 발급받아야 합니다. 계정 삭제 기능을 사용하지 않는 경우 false로 설정합니다.

Response header¶

필드명	설명	타입
Authorization	세션 토큰. `require_token: true`인 경우에만 발급	String
Content-Type	응답 데이터 형식(JSON) 및 문자 인코딩(UTF-8) 정보	String
ISCRYPT	응답 암호화 여부	Integer

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data.player_id	`PlayerID`	BigInteger
data.idp_index	IdP 인덱스	Integer
data.idp_id	IdP 이름	String
data.idp_user_id	IdP 사용자 ID	String

응답 코드¶

코드값	설명
0	성공
2499	JWT 검증 실패 (token_validation 참고)
4000	유효하지 않은 파라미터
4001	request JSON 오류
4200	존재하지 않는 IdP
5000	서버 내부 오류
7000	유효하지 않은 토큰
7001	header에 토큰 값 없음

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 3,
    "idp_user_id": "google_67890",
    "require_token": true
}

Response example¶

HTTP/1.1 200
Content-Type: application/json; charset=UTF-8
Authorization: abcdf7ebce779429ea878f91d5f1c8
ISCRYPT: 0

성공¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    },
    "data": {
        "player_id": 100000002,
        "idp_index": 3,
        "idp_id": "GOOGLE",
        "idp_user_id": "google_67890"
    }
}

IdP 연동¶

기존 플레이어 계정에 새로운 IdP를 연동합니다. Player ID가 생성된 상태에서만 IdP 연동이 가능합니다.

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/connect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/connect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
idp_index	IdP 인덱스 코드. IdP 인덱스 참조 참고	Integer	Y
idp_user_id	IdP 사용자 고유 식별자	String	Y
player_id	연동할 `PlayerID`	BigInteger	Y

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String
data.player_id	`PlayerID`	BigInteger
data.idp_index	연동된 IdP 인덱스	Integer
data.idp_id	연동된 IdP 이름	String
data.idp_user_id	IdP 사용자 ID	String

응답 코드¶

코드값	설명
0	성공
1002	해당 IdP가 다른 플레이어에 이미 연동됨
1003	동일한 IdP 타입이 이미 연동됨
2002	존재하지 않는 플레이어
2499	JWT 검증 실패 (token_validation 참고)
4000	유효하지 않은 파라미터
4200	존재하지 않는 IdP
5000	서버 내부 오류
7000	유효하지 않은 토큰
7001	header에 토큰 값 없음

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001
}

Response example¶

성공¶

{
    "result_code": 0,
    "result_msg": "SUCCESS",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    },
    "data": {
        "player_id": 100000001,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

다른 플레이어에 이미 연동된 경우¶

{
    "result_code": 1002,
    "result_msg": "Already connected other player",
    "token_validation": {
        "result_code": 0,
        "result_msg": "success"
    },
    "data": {
        "player_id": 100000002,
        "idp_index": 2,
        "idp_id": "FACEBOOK",
        "idp_user_id": "fb_12345678"
    }
}

IdP 연동 해제¶

플레이어 계정과 연동된 IdP를 해제합니다. PlayerID가 생성된 상태에서만 IdP 연동 해제가 가능합니다.

Request URL¶

상용 URL	https://auth.qpyou.cn/v2/game/auth/disconnect
Sandbox URL	https://sandbox-auth.qpyou.cn/v2/game/auth/disconnect
HTTP Method	POST
Content-Type	application/json
Data Format	JSON

Request header¶

필드명	설명	타입	필수 여부
X-Access-Token	앱 서버 인증을 위한 OAuth 2.0 Access Token (OAuth Token 발급하기 참고)	String	Y
ISCRYPT	데이터 암호화 여부 (0 = 암호화 안 함) (무조건 0으로 전달)	Integer	Y

Request body¶

필드명	설명	타입	필수 여부
appid	App ID	String	Y
idp_index	IdP 인덱스 코드. IdP 인덱스 참조 참고	Integer	Y
idp_user_id	IdP 사용자 고유 식별자	String	Y
player_id	연동 해제할 `PlayerID`	BigInteger	Y

Response body¶

필드명	설명	타입
result_code	응답 코드 자세히	Integer
result_msg	결과 메시지	String
token_validation	JWT 검증 결과 (JWT 검증 에러)	Object
token_validation.result_code	JWT 검증 결과 코드	Integer
token_validation.result_msg	JWT 검증 결과 메시지	String

응답 코드¶

코드값	설명
0	성공
2499	JWT 검증 실패 (token_validation 참고)
4000	유효하지 않은 파라미터
4006	연동된 IdP 정보 없음
4200	존재하지 않는 IdP
7000	유효하지 않은 토큰
7001	header에 토큰 값 없음

Request example¶

{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "idp_index": 2,
    "idp_user_id": "fb_12345678",
    "player_id": 100000001
}

Response example¶

성공¶

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

Note

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

IdP 계정 관리¶

IdP 로그인¶

Request URL¶

Request header¶

Request body¶

Response header¶

Response body¶

응답 코드¶

Request example¶

Response example¶

Header¶

성공¶

IdP 연동¶

Request URL¶

Request header¶

Request body¶

Response body¶

응답 코드¶

Request example¶

Response example¶

성공¶

다른 플레이어에 이미 연동된 경우¶

IdP 연동 해제¶

Request URL¶

Request header¶

Request body¶

Response body¶

응답 코드¶

Request example¶

Response example¶

성공¶