> ## Documentation Index
> Fetch the complete documentation index at: https://playwave.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API 개요

> PlayWave Game Server API 인증, Base URL, 응답 형식

## Base URL

| 환경       | URL                                   | 상태                                 |
| -------- | ------------------------------------- | ---------------------------------- |
| **Dev**  | `https://wave-api.playwave.dev/v1`    | <Badge color="green">사용 가능</Badge> |
| **QA**   | `https://wave-api-qa.playwave.dev/v1` | <Badge color="yellow">준비 중</Badge> |
| **Live** | `https://wave-api.playwave.io/v1`     | <Badge color="yellow">준비 중</Badge> |

## 인증

모든 요청에 `X-Api-Key` 헤더가 필요합니다.

<ParamField header="X-Api-Key" type="string" required>
  게임별 API Key. 서버에서 <Tooltip tip="API Key를 고정 길이 다이제스트로 변환하여 안전하게 비교하는 암호화 해시 함수">SHA-256 해시</Tooltip>를 게임 설정과 매칭하여 인증합니다.
</ParamField>

<Info>
  API Key는 현재 PlayWave 서비스 운영 담당자에게 요청하여 발급받을 수 있습니다. 담당자에게 연락하여 게임별 키를 요청하세요.
</Info>

<ParamField header="Content-Type" type="string" required>
  `application/json`이어야 합니다.
</ParamField>

<Warning>
  API Key는 서버 사이드에서만 사용하세요. 클라이언트에 노출되면 즉시 콘솔에서 재발급하세요.
</Warning>

## 응답 형식

### 성공 응답

```json theme={null}
{
  "success": true,
  "request_id": "req_abc123",
  "data": {
    // 엔드포인트별 응답 데이터
  }
}
```

### 에러 응답

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key is invalid or inactive",
    "timestamp": "2026-03-06T12:00:00.000Z"
  }
}
```

## 엔드포인트 목록

게임 서버에서 호출하는 API는 3개입니다.

| Method                            | Path                                                        | 설명                                                                                      |
| --------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| <Badge color="green">POST</Badge> | [`/v1/game/session/verify`](/ko/api-reference/verify)       | <Tooltip tip="One-Time Token — 런처에서 게임 서버로 세션을 전달하는 1회용 토큰">OTT</Tooltip> 검증 + 게임 세션 생성 |
| <Badge color="blue">PATCH</Badge> | [`/v1/game/session/heartbeat`](/ko/api-reference/heartbeat) | 게임 세션 하트비트 (2분 간격)                                                                      |
| <Badge color="red">DELETE</Badge> | [`/v1/game/session/end`](/ko/api-reference/end)             | 게임 세션 종료                                                                                |

## 공통 에러 코드

| 코드                | HTTP                              | 설명          |
| ----------------- | --------------------------------- | ----------- |
| `BAD_REQUEST`     | <Badge color="yellow">400</Badge> | 요청 본문 검증 실패 |
| `INVALID_API_KEY` | <Badge color="yellow">401</Badge> | API Key 무효  |
| `RATE_LIMITED`    | <Badge color="orange">429</Badge> | 요청 빈도 제한 초과 |
| `INTERNAL_ERROR`  | <Badge color="red">500</Badge>    | 서버 내부 오류    |