Skip to content

인증과 서명 ​

모든 요청은 https://game-api.webzenk.kr로 보내요. 요청은 세 가지 방식으로 인증하고, 로그인한 뒤에는 유저 토큰(Authorization: Bearer)을 더해요.

구분누가헤더
앱 서명모바일·PC 클라이언트X-App-Key, X-Timestamp, X-Nonce, X-Signature (App Secret)
웹HTML5·WebGL (브라우저)X-App-Key (+ 브라우저의 Origin이 허용 도메인이어야 함)
서버 서명개발사 서버앱 서명과 같은 방식, 키만 Server Secret

API 문서의 인증 표시: 앱 = 로그인 전 · 유저 = Access Token 필요 · 서버 = Server Secret 서명

서명 만들기 ​

text
string_to_sign = METHOD + "\n"
               + REQUEST_URI + "\n"      // 경로 + 쿼리 (보내는 그대로). 예: /v1/leaderboards/weekly/top?limit=50
               + X-Timestamp + "\n"      // epoch 초
               + X-Nonce + "\n"          // 요청마다 새 무작위 값 8~64자 [A-Za-z0-9_-]
               + SHA256_HEX(body)        // 본문이 없으면 빈 문자열의 SHA-256

X-Signature = Base64( HMAC-SHA256(key = Secret, message = string_to_sign) )
  • 쿼리가 없으면 ?를 붙이지 마세요. 끝에 빈 ?가 있으면 빼고 서명해요.
  • 쿼리스트링은 보내는 문자열 그대로 서명해요 (정렬·재인코딩하지 않음).
  • 서버 시각과 ±300초 넘게 차이 나면 TIMESTAMP_SKEW예요. 오류 응답의 server_time으로 보정해 다시 보내세요.
  • 같은 Nonce는 10분 안에 다시 쓸 수 없어요 (REPLAYED_REQUEST).
csharp
static string Sign(string secret, string method, string uri, string ts, string nonce, string body)
{
    using var sha = SHA256.Create();
    var bodyHash = Convert.ToHexString(sha.ComputeHash(Encoding.UTF8.GetBytes(body))).ToLowerInvariant();
    var msg = $"{method}\n{uri}\n{ts}\n{nonce}\n{bodyHash}";
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    return Convert.ToBase64String(h.ComputeHash(Encoding.UTF8.GetBytes(msg)));
}
js
import crypto from 'node:crypto'

function sign(secret, method, uri, ts, nonce, body = '') {
  const bodyHash = crypto.createHash('sha256').update(body).digest('hex')
  const msg = `${method}\n${uri}\n${ts}\n${nonce}\n${bodyHash}`
  return crypto.createHmac('sha256', secret).update(msg).digest('base64')
}

const body = JSON.stringify({ device_id: 'device-1234' })
const ts = String(Math.floor(Date.now() / 1000))
const nonce = crypto.randomBytes(12).toString('hex')
await fetch('https://game-api.webzenk.kr/v1/auth/guest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json', 'X-App-Key': APP_KEY, 'X-Timestamp': ts, 'X-Nonce': nonce,
    'X-Signature': sign(APP_SECRET, 'POST', '/v1/auth/guest', ts, nonce, body),
  },
  body,
})
php
function sign(string $secret, string $method, string $uri, string $ts, string $nonce, string $body = ''): string
{
    $msg = $method . "\n" . $uri . "\n" . $ts . "\n" . $nonce . "\n" . hash('sha256', $body);
    return base64_encode(hash_hmac('sha256', $msg, $secret, true));
}

유저 토큰 ​

  • 로그인하면 access_token(기본 1시간)과 refresh_token(기본 30일)을 받아요. 유저 API에는 Authorization: Bearer <access_token>을 붙여요.
  • Access Token이 만료되면 401 AUTH_TOKEN_INVALID예요. POST /v1/auth/refresh로 새 토큰을 받고 다시 호출하세요.
  • Refresh Token은 쓸 때마다 바뀌어요. 이미 쓴 Refresh Token을 다시 쓰면 그 유저의 모든 세션을 끊어요 (REFRESH_TOKEN_REUSED). 새 토큰을 꼭 저장하세요.

웹 규칙 ​

  • X-App-Key만 보내고 서명 헤더는 보내지 않아요. 게임 주소가 허용 도메인이어야 해요 (ORIGIN_NOT_ALLOWED, WEB_NOT_ENABLED).
  • Google Play·App Store 결제 검증과 AppLovin 광고 세션은 웹에서 쓸 수 없어요 (WEB_NOT_SUPPORTED).
  • CORS는 클라이언트 API에만 열려 있어요. 개발사 서버 API는 브라우저에서 호출할 수 없어요.

© WEBZEN K. All rights reserved.