---
url: https://developers.webzenk.kr/api/auth.md
---
# 로그인·계정

| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/auth/guest` | 앱 | 게스트 로그인 |
| POST | `/v1/auth/google` | 앱 | Google / Play Games |
| POST | `/v1/auth/apple` | 앱 | Sign in with Apple |
| POST | `/v1/auth/platform/{platform}` | 앱 | HTML5 플랫폼 계정 (`samsung`) |
| POST | `/v1/auth/refresh` | 앱 | 토큰 갱신 |
| POST | `/v1/auth/link` | 유저 | 로그인 수단 연결 |
| GET | `/v1/players/me` | 유저 | 내 정보 |
| POST | `/v1/auth/logout` | 유저 | 로그아웃 |
| DELETE | `/v1/account` | 유저 | 탈퇴 요청 |
| POST | `/v1/account/restore` | 유저 | 탈퇴 철회 |

## 로그인

모든 로그인 API는 같은 응답을 돌려줍니다. `device_id`는 8~128자 `[A-Za-z0-9._:-]`.

| API | 본문 |
|---|---|
| `/v1/auth/guest` | `{ "device_id": "…" }` — 같은 ID면 같은 유저 |
| `/v1/auth/google` | `{ "id_token": "…", "device_id": "…"? }` 또는 Play Games `{ "server_auth_code": "…" }` |
| `/v1/auth/apple` | `{ "identity_token": "…", "nonce": "원문"?, "device_id": "…"? }` |
| `/v1/auth/platform/samsung` | `{ "signature": "GSInstant.player.getSignatureAsync() 결과" }` |

```json
{
  "player_id": "1024",
  "token_type": "Bearer",
  "access_token": "eyJhbGciOi…",
  "expires_in": 3600,
  "refresh_token": "…",
  "refresh_expires_in": 2592000,
  "is_new": true,
  "deletion_requested_at": null
}
```

`deletion_requested_at`이 있으면 탈퇴 유예 중입니다. "탈퇴 철회" 화면을 보여 주세요.

| 오류 | 뜻 |
|---|---|
| `401 INVALID_PROVIDER_TOKEN` | 토큰 검증 실패 (만료·클라이언트 ID 미등록) |
| `400 PROVIDER_NOT_CONFIGURED` | 이 게임에 해당 로그인 연동이 없음 |
| `403 PLAYER_BANNED` / `PLAYER_DELETED` | 제재 / 파기된 유저 |

## 토큰 갱신

POST `/v1/auth/refresh` — `{ "refresh_token": "…", "device_id": "…"? }` → 로그인과 같은 응답 (새 토큰 쌍)

Refresh Token은 한 번만 쓸 수 있습니다. 응답의 새 `refresh_token`을 꼭 저장하세요.

| 오류 | 대응 |
|---|---|
| `REFRESH_TOKEN_EXPIRED` · `INVALID` · `REVOKED` | 다시 로그인 |
| `REFRESH_TOKEN_REUSED` | 이미 쓴 토큰 재사용 — 탈취 의심으로 모든 세션 종료. 다시 로그인 |

## 계정 연결

POST `/v1/auth/link` — `{ "provider": "google" | "apple" | "samsung", …해당 로그인 API와 같은 필드 }` → 내 정보

`409 ALREADY_LINKED` 다른 유저에 연결된 계정 · `409 PROVIDER_ALREADY_LINKED` 같은 종류 계정이 이미 연결됨

## 내 정보

GET `/v1/players/me`

```json
{ "player_id": "1024", "status": "active", "providers": ["guest", "google"],
  "created_at": 1795000000, "last_login_at": 1795055000, "deletion_requested_at": null }
```

`status`: `active` · `banned` · `delete_requested` · `deleted`

## 로그아웃

POST `/v1/auth/logout` — `{ "refresh_token": "…" }` 이 기기 세션만 종료

## 탈퇴

DELETE `/v1/account` — 모든 세션 종료, 유예 기간 후 파기

```json
{ "deletion_requested_at": 1795055466, "purge_after": 1797647466 }
```

POST `/v1/account/restore` — 유예 기간 중 철회 → 내 정보. 자세한 내용은 [개인정보·탈퇴](/guide/privacy).
