---
url: https://developers.webzenk.kr/api.md
---
# 인증과 서명

모든 요청은 `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`).

::: code-group

```csharp [C#]
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 [JavaScript (Node)]
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 [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`](./auth#토큰-갱신)로 새 토큰을 받고 다시 호출하세요.
* 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는 브라우저에서 호출할 수 없어요.
