OAuth Token 발급¶

Hive Server API 호출 시 권한 검증 및 보안 인증에 필요한 OAuth Token을 발급 받습니다.

'OAuth Token 발급' API는 OAuth 2.0 표준 사양인 Client Credentials Grant 방식을 따르며, 앱 서버에서 Hive 인증 서버로 직접 호출하는 서버 간(Server-to-Server) 인증 흐름으로 동작합니다.

'OAuth Token 발급' API는 아래와 같은 특징을 갖습니다.

• Client ID와 Secret만으로 토큰 발급
• Access Token만 발급 (Refresh Token 미발급)
• 1시간 유효기간 (3600초)

Request URL¶

Request header¶

Request body¶

Request example¶

curl¶

curl -X POST https://auth.qpyou.cn/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "grant_type": "client_credentials",
    "client_id": "project_abc123",
    "client_secret": "secret_xyz789"
  }'

Body¶

{
  "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
  "grant_type": "client_credentials",
  "client_id": "project_abc123",
  "client_secret": "secret_xyz789"
}

Response Body¶

응답 코드¶

Response example¶

{
  "result_code": 0,
  "result_msg": "SUCCESS",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0.eyJwcm9qZWN0X2lkIjoiY29tLmNvbTJ1cy5leGFtcGxlIiwidG9rZW5fdHlwZSI6ImFjY2Vzc190b2tlbiIsImdyYW50X3R5cGUiOiJwcm9qZWN0IiwiaWF0IjoxNzE1NTg0MDAwLCJleHAiOjE3MTU1ODc2MDAsImF1dGhfdmVyIjoidjQiLCJ1c2VyX2lkIjoiIiwiaXNfd2hpdGVsaXN0Ijp0cnVlfQ.signature"
  }
}

에러 응답 예시¶

{
  "result_code": 4001,
  "result_msg": "INVALID_CLIENT",
  "data": null
}

토큰 사용 방법¶

발급받은 Access Token은 HIVE Server API 호출 시 HTTP 헤더에 포함하여 사용합니다.

JWT 토큰 구조¶

발급받은 Access Token은 JWT(JSON Web Token) 형식이며, .로 구분된 세 부분(Header.Payload.Signature)으로 구성됩니다.

Header¶

Payload¶

헤더 설정¶

사용 예시¶

curl -X POST https://auth.qpyou.cn/v2/game/player/get-idp \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..." \
  -H "ISCRYPT: 0" \
  -d '{
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "player_id": 123456789
  }'

JWT 토큰 검증 에러¶

Hive Server API에서 JWT 토큰 검증 실패 시, token_validation 필드를 통해 상세한 에러 정보를 제공합니다.

token_validation 필드¶

JWT 검증 관련 에러 정보를 담고 있는 필드입니다:

에러 응답 예시¶

클라이언트 정보 없음¶

"token_validation": {
  "result_code": 2400,
  "result_msg": "No client information found."
}

토큰 누락¶

"token_validation": {
  "result_code": 2406,
  "result_msg": "The access token is missing."
}

토큰 서명 오류¶

"token_validation": {
  "result_code": 2407,
  "result_msg": "Invalid token signature."
}

토큰 만료¶

"token_validation": {
  "result_code": 2408,
  "result_msg": "The access token is expired. Please refresh your token."
}

JWT 검증 에러 코드¶

정상 응답¶

JWT 검증이 성공한 경우:

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

토큰 갱신¶

Client Credentials Grant에서는 Refresh Token이 발급되지 않습니다.

토큰 만료 시 처리¶

1. Access Token 만료 (발급 후 1시간)
2. API 호출 시 JWT 검증 실패 (token_validation.result_code: 2408)
3. /oauth/token API를 호출하여 새로운 Access Token 재발급

토큰 재사용 권장¶

Access Token은 만료 전까지 재사용할 수 있습니다.

권장 사항:

• ✅ 권장: 발급받은 토큰을 캐싱하여 만료 전까지 재사용
• ❌ 비권장: API 호출마다 새 토큰 발급

보안 권장사항¶

Client Secret 관리¶

Client Secret은 민감한 정보이므로 안전하게 관리해야 합니다.

HTTPS 필수¶

OAuth Token 발급 및 API 호출 시 반드시 HTTPS를 사용해야 합니다.

• ✅ 권장: https://auth.qpyou.cn/oauth/token
• ❌ 금지: http:// 사용 (중간자 공격에 취약)