본문으로 건너뛰기
버전: 0.68.0

사용자 로그아웃 API

사용자 로그아웃 API는 현재 로그인된 사용자의 세션을 안전하게 종료하고 관련 토큰들을 무효화하는 과정을 처리합니다.

사용자 로그아웃​

사용자의 액세스 토큰과 리프레시 토큰을 모두 무효화하여 세션을 안전하게 종료합니다.

  • HTTP Method: POST
  • Path: v1/auth/logout
  • 인증: 필요 (Bearer Access Token)

Headers​

HeaderTypeDescriptionRequired
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes
AuthorizationBearer <token>사용자의 유효한 액세스 토큰을 포함해야 합니다.Yes
Accept-LanguageLanguage Code사용자 선호 언어를 지정합니다. 지역 코드를 포함한 형식만 지원합니다.No

Responses​

HTTP Status Code설명Error Code(s)
200 OK로그아웃 성공-
401 Unauthorized인증 실패 (예: 유효하지 않거나 만료된 토큰)2051, 2003
500 Internal Server Error서버 내부 오류2000
200 OK - 로그아웃 성공

성공적으로 로그아웃하면 성공 여부를 나타내는 boolean 값이 반환됩니다.

{
  "success": true
}
필드타입설명예시필수 (Yes/No)
successboolean로그아웃 성공 여부trueYes
401 Unauthorized - 인증 실패

예시: 유효하지 않은 액세스 토큰

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

이 오류는 제공된 액세스 토큰이 유효하지 않은 경우 발생합니다. (예: 형식 오류, 서명 불일치, 이미 무효화됨 등). InvalidTokenError에 해당합니다.

예시: 액세스 토큰 만료

{
  "code": 2003, // AuthErrorCode.ACCESS_TOKEN_EXPIRED
  "message": "ACCESS_TOKEN_EXPIRED",
  "detail": "액세스 토큰이 만료되었습니다."
}

이 오류는 제공된 액세스 토큰이 만료되었을 때 발생합니다. AccessTokenExpiredError에 해당합니다.

500 Internal Server Error - 서버 내부 오류
{
  "code": 2000, // AuthErrorCode.SERVER_ERROR
  "message": "SERVER_ERROR",
  "detail": "서버 내부 오류"
}

이 오류는 로그아웃 처리 중 예기치 않은 서버 내부 문제가 발생했을 때 반환될 수 있습니다. ServerError에 해당합니다.

설명​

  • 이 API는 사용자의 현재 세션을 안전하게 종료하고 관련된 모든 토큰을 무효화합니다.
  • 주요 처리 단계:
    1. 요청 헤더에서 액세스 토큰 추출 및 유효성 검증.
    2. 토큰에서 사용자 정보 추출.
    3. 토큰 스테이징 처리 (AUT-FR-BE-029):
      • 현재 액세스 토큰을 :staging 상태로 전환.
      • :staging 상태의 토큰을 Redis 캐시에 set 형태로 저장.
      • TTL(Time-to-Live)을 5분으로 설정
    4. 사용자와 연관된 모든 리프레시 토큰 무효화.
    5. 데이터베이스에서 토큰 상태를 REVOKED로 업데이트.
    6. 응답 반환.

변경 이력​

버전날짜작성자변경 내용
0.1.02025-09-12bok@weltcorp.com최초 문서 작성 - 토큰 스테이징 정책 (AUT-FR-BE-029) 반영
0.1.12025-09-15bok@weltcorp.com응답 구조를 실제 구현에 맞게 수정 (success boolean 필드)