게스트 로그인 API

게스트 로그인 API는 이미 등록된 게스트 계정으로 다시 로그인하기 위한 인증 과정을 처리합니다. 성공적인 로그인 시, 새로운 액세스 토큰과 리프레시 토큰이 발급됩니다.

공통 요청 헤더

모든 dha-sleep API 요청은 공통 요청 헤더를 준수해야 합니다. User-Agent, Accept-Language, 인증 헤더 요구사항을 먼저 확인하세요.

참고

게스트 로그인을 위해서는 먼저 앱 인증을 통해 appToken을 획득해야 합니다.

게스트 로그인

디바이스 UUID를 사용하여 기존 게스트 계정에 로그인하고, 새로운 토큰을 발급받습니다.

• HTTP Method: POST
• Path: /v1/auth/guest/login (API_PREFIX 기본값이 v1이며 환경에 따라 변경 가능)
• 인증: appToken 필요 (Authorization: Bearer {appToken})

Headers

Header	Type	Description	Required
Authorization	string	앱 인증 토큰 (Bearer {appToken})	Yes
Content-Type	application/json	요청 본문 형식을 지정합니다.	Yes
User-Agent	string	User-Agent 헤더 (format: <product>/<version> (<platform>; <os>; <device>; <channel>; locale/<locale>))	Yes

Request Body

{
  "deviceUuid": "e8e53358-c282-4f69-89c4-bae40f0b7587"
}

필드	타입	설명	필수
deviceUuid	string	디바이스 UUID. 게스트 등록 시 사용한 것과 동일한 값	Yes

Responses

응답 형식

게스트 로그인 API의 성공 응답 형식은 게스트 등록 API의 응답 형식과 동일합니다. 클라이언트에서 두 API의 응답을 동일한 데이터 모델로 처리할 수 있습니다 (로그인 응답에는 nextStepMessage 필드가 없음).

HTTP Status Code	설명	Error Code(s)
200 OK	로그인 성공	-
400 Bad Request	잘못된 요청 (예: 유효하지 않은 디바이스 ID)	2011
401 Unauthorized	앱 토큰 인증 실패	2051
404 Not Found	게스트 계정을 찾을 수 없음	2060
410 Gone	게스트 계정이 만료됨 또는 업그레이드됨	2061
500 Internal Server Error	서버 내부 오류	2000

200 OK - 로그인 성공

성공적으로 로그인하면 GuestLoginResponseDto에 정의된 게스트 세션 정보가 반환됩니다. 여기에는 인증 토큰, 게스트 계정 정보, 프로필 정보, 역할, 권한 및 동의한 약관 목록이 포함됩니다.

{
  "tokens": [
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "type": "ACCESS_TOKEN",
      "expiresIn": 900,
      "issuedAt": 1714523700000
    },
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "type": "REFRESH_TOKEN",
      "expiresIn": 43200,
      "issuedAt": 1714523700000
    }
  ],
  "user": {
    "id": "guest_a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6",
    "identityLevel": "GUEST",
    "createdAt": 1714520000000,
    "expiresAt": 1714606400000
  },
  "userCycle": {
    "id": "d2f8e5c1-9b3a-4f8c-8e2f-1b9a3c5e2d7c",
    "status": "ACTIVE",
    "startedAt": 1714520000000,
    "count": 1,
    "treatmentDurationDays": -1
  },
  "profile": {
    "language": "ko-KR",
    "timezone": {
      "id": "Asia/Seoul",
      "offsetInMinutes": 540
    }
  },
  "roles": ["guest.user"],
  "permissions": ["sleep.log.create", "sleep.log.read", "content.read"],
  "agreements": [
    {
      "versionId": "9f8a7b6c-5d4e-3f2g-1h0i-j9k8l7m6n5o4",
      "type": "TERMS",
      "isRequired": true,
      "text": "서비스 이용약관",
      "detailsUrl": "https://www.example.com/terms",
      "isAgreed": true,
      "agreedAt": 1714520000000
    }
  ]
}

필드	타입	설명	예시	필수
tokens	array	인증 토큰 정보 배열. 정확히 2개의 토큰(access token과 refresh token)을 포함합니다.		Yes
tokens[].token	string	JWT 토큰 값	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...	Yes
tokens[].type	string	토큰 타입	ACCESS_TOKEN 또는 REFRESH_TOKEN	Yes
tokens[].expiresIn	number	토큰 만료 시간 (초)	900	Yes
tokens[].issuedAt	number	토큰 발급 시간 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	1714523700000	Yes
user	object	사용자(게스트) 계정 정보		Yes
user.id	string	사용자 계정 ID	guest_a1b2c3d4-...	Yes
user.identityLevel	string	신원 수준 (게스트의 경우 GUEST)	GUEST	Yes
user.createdAt	number	계정 생성일 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	1714520000000	Yes
user.expiresAt	number	세션 만료일 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	1714606400000	No
userCycle	object	사용자 주기 정보 (정식 사용자 login API의 userCycle과 동일한 형식)		Yes
userCycle.id	string	사용자 주기 ID	d2f8e5c1-9b3a-4f8c-8e2f-1b9a3c5e2d7c	Yes
userCycle.status	string	사용자 주기 상태	ACTIVE	Yes
userCycle.startedAt	number	주기 시작일 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)	1714520000000	Yes
userCycle.count	number	해당 사용자의 총 주기 개수 (게스트는 항상 1)	1	Yes
userCycle.treatmentDurationDays	number	치료 주기의 총 기간 (일수, Kotlin: Int, Swift: Int). 게스트는 -1 (무제한)	-1	Yes
profile	object	사용자 프로필 정보		Yes
profile.language	string	사용자 언어 설정 (예: ko-KR, de-DE)	ko-KR	Yes
profile.timezone	object	사용자 시간대 정보		Yes
profile.timezone.id	string	시간대 ID (예: Asia/Seoul)	Asia/Seoul	Yes
profile.timezone.offsetInMinutes	number	UTC 기준 오프셋 (분 단위, Kotlin: Int, Swift: Int)	540	Yes
roles	string[]	게스트 역할 목록	["guest.user"]	Yes
permissions	string[]	게스트 권한 목록	["sleep.log.create", "sleep.log.read"]	Yes
agreements	object[]	동의한 약관 목록		Yes
agreements[].versionId	string	약관 버전 ID		Yes
agreements[].type	string	약관 타입 (TERMS, CONSENT, PRIVACY_POLICY)	TERMS	Yes
agreements[].isRequired	boolean	필수 약관 여부		Yes
agreements[].text	string	약관 요약 텍스트		Yes
agreements[].detailsUrl	string	약관 상세 URL		Yes
agreements[].isAgreed	boolean	동의 여부		Yes
agreements[].agreedAt	number	동의 시각 (Unix timestamp in milliseconds, Kotlin: Long, Swift: Int64)		Yes

400 Bad Request - 잘못된 요청

예시: 디바이스 ID 오류

{
  "code": 2011,
  "message": "INVALID_DEVICE_ID",
  "detail": "디바이스 ID가 유효하지 않거나 필수 필드가 누락되었습니다",
  "errors": [
    {
      "field": "device.uuid",
      "message": "device.uuid는 필수입니다."
    }
  ]
}

401 Unauthorized - 인증 실패

{
  "code": 2051,
  "message": "INVALID_TOKEN",
  "detail": "토큰이 유효하지 않습니다"
}

404 Not Found - 게스트 계정을 찾을 수 없음

{
  "code": 2060,
  "message": "GUEST_ACCOUNT_NOT_FOUND",
  "detail": "해당 디바이스로 등록된 게스트 계정을 찾을 수 없습니다"
}

이 오류는 해당 디바이스 UUID로 등록된 게스트 계정이 존재하지 않을 때 발생합니다. 게스트 등록을 먼저 진행해야 합니다.

410 Gone - 게스트 계정 만료 또는 업그레이드됨

예시: 게스트 계정 만료

{
  "code": 2061,
  "message": "GUEST_ACCOUNT_EXPIRED",
  "detail": "게스트 계정이 만료되었습니다. 정식 가입을 진행해주세요.",
  "metadata": {
    "expiredAt": 1714606400000
  }
}

예시: 정식 사용자로 업그레이드됨

{
  "code": 2062,
  "message": "GUEST_ACCOUNT_UPGRADED",
  "detail": "게스트 계정이 정식 사용자로 업그레이드되었습니다. 정식 로그인을 사용해주세요."
}

이 오류는 게스트 계정이 만료되었거나 Step-up 인증을 통해 정식 사용자로 업그레이드된 경우 발생합니다.

500 Internal Server Error - 서버 내부 오류

{
  "code": 2000,
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

설명

전체 프로세스 가이드

게스트 등록 및 로그인 프로세스의 전체 흐름은 게스트 등록 프로세스 가이드를 참고하세요.

게스트 로그인 vs 게스트 등록

항목	게스트 등록	게스트 로그인
용도	새 게스트 계정 생성	기존 게스트 계정으로 재로그인
필수 입력	deviceUuid, agreements, profile	deviceUuid만 필요
응답	{ success: true }	tokens + user + userCycle 등
사용 시점	앱 최초 실행 또는 재설치 후	앱 재시작 또는 토큰 만료 후

토큰 갱신

게스트 로그인 성공 시 발급받은 토큰의 유효 기간:

• Access Token: 15분 (expiresIn: 900)
• Refresh Token: 12시간 (expiresIn: 43200)

토큰 만료 전에 토큰 갱신 API를 사용하여 새로운 토큰을 발급받을 수 있습니다.

게스트 계정 제한사항

게스트 계정은 제한된 신원 수준(Identity Level: GUEST)으로 다음과 같은 제한이 있습니다:

• 일부 기능만 접근 가능 (permissions 참조)
• 정식 사용자 전용 기능(보고서 다운로드, 데이터 동기화 등) 사용 불가
• Step-up 인증을 통해 정식 사용자로 업그레이드 가능

오류 코드 참조

코드	메시지	설명
2000	SERVER_ERROR	서버 내부 오류
2011	INVALID_DEVICE_ID	디바이스 ID가 유효하지 않음
2051	INVALID_TOKEN	앱 토큰이 유효하지 않음
2060	GUEST_ACCOUNT_NOT_FOUND	해당 디바이스의 게스트 계정이 존재하지 않음
2061	GUEST_ACCOUNT_EXPIRED	게스트 계정이 만료됨
2062	GUEST_ACCOUNT_UPGRADED	게스트 계정이 정식 사용자로 업그레이드됨