화면 모드
인증과 서명
모든 요청은 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는 브라우저에서 호출할 수 없어요.