화면 모드
로그인·계정
| 경로 | 인증 | 설명 | |
|---|---|---|---|
| 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/mejson
{ "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
POST { "deletion_requested_at": 1795055466, "purge_after": 1797647466 }/v1/account/restore — 유예 기간 중 철회 → 내 정보. 자세한 내용은 개인정보·탈퇴.