본문으로 건너뛰기
버전: 개발 버전 (최신)

토큰 갱신 API

토큰 갱신 API는 만료된 액세스 토큰을 유효한 리프레시 토큰을 사용하여 새로 발급받기 위한 과정을 처리합니다.

공통 요청 헤더

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

참고

토큰 갱신을 위해서는 앱 인증을 통해 획득한 appToken과 유효한 refreshToken이 필요합니다.

토큰 갱신​

리프레시 토큰을 사용하여 새로운 액세스 토큰과 리프레시 토큰 쌍을 발급합니다.

  • HTTP Method: POST
  • Path: /v1/auth/token/refresh
  • 인증: appToken 필요 (Authorization: Bearer {appToken})

Headers​

HeaderTypeDescriptionRequired
Authorizationstring앱 인증 토큰 (Bearer {appToken})Yes
Content-Typeapplication/json요청 본문 형식을 지정합니다.Yes

Request Body​

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
필드타입설명필수
refreshTokenstring사용자가 보유한 유효한 리프레시 토큰Yes

Responses​

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

성공적으로 토큰을 갱신하면 RefreshTokenResponseDto에 정의된 새로운 토큰 정보가 반환됩니다.

{
  "tokens": [
    {
      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...new_access_token",
      "type": "ACCESS_TOKEN",
      "expiresIn": 900,
      "issuedAt": 1714524000000
    },
    {
      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...new_refresh_token",
      "type": "REFRESH_TOKEN",
      "expiresIn": 43200,
      "issuedAt": 1714524000000
    }
  ]
}
필드타입설명예시필수
tokensarray인증 토큰 정보 배열 (TokenResponseDto[]). 정확히 2개의 토큰(새로운 access token과 새로운 refresh token)을 포함해야 합니다.Yes
tokens[].tokenstring토큰 값eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...Yes
tokens[].typestring토큰 타입 (ACCESS_TOKEN 또는 REFRESH_TOKEN)ACCESS_TOKENYes
tokens[].expiresInnumber토큰 만료 시간 (초 단위)900Yes
tokens[].issuedAtnumber토큰 발급 시간 (Unix timestamp in milliseconds)1714524000000Yes
토큰 만료 시간
  • 게스트 사용자: Access Token 15분 (900초), Refresh Token 12시간 (43200초)
  • 정식 사용자: Access Token 30분 (1800초), Refresh Token 14일 (1209600초)
401 Unauthorized - 인증 실패

예시: 유효하지 않은 토큰

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

이 오류는 제공된 리프레시 토큰이 유효하지 않은 경우 발생합니다. (예: 형식 오류, 서명 불일치, 데이터베이스에 존재하지 않음, 이미 사용됨, 폐기됨 등)

예시: 리프레시 토큰 만료

{
  "code": 2003,
  "message": "REFRESH_TOKEN_EXPIRED",
  "detail": "리프레시 토큰이 만료되었습니다."
}

이 오류는 제공된 리프레시 토큰이 만료되었을 때 발생합니다.

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

이 오류는 토큰 갱신 처리 중 예기치 않은 서버 내부 문제가 발생했을 때 반환될 수 있습니다.

설명​

토큰 갱신 프로세스​

  1. 클라이언트가 유효한 리프레시 토큰을 요청 본문에 포함하여 API를 호출합니다.
  2. 서버는 리프레시 토큰의 유효성을 검증합니다:
    • 토큰 형식 및 서명 확인
    • 데이터베이스에서 토큰 상태 확인 (ACTIVE 상태여야 함)
    • 토큰 만료 여부 확인
  3. 검증이 성공하면 새로운 액세스 토큰과 리프레시 토큰을 생성합니다.
  4. 기존 리프레시 토큰은 폐기(revoke)되고, 새로운 토큰 쌍이 반환됩니다.

토큰 로테이션​

dha-sleep API는 리프레시 토큰 로테이션 정책을 사용합니다. 토큰 갱신 시 기존 리프레시 토큰은 폐기되고 새로운 리프레시 토큰이 발급됩니다. 클라이언트는 반드시 응답으로 받은 새 리프레시 토큰을 저장하고 다음 갱신 시 사용해야 합니다.

중요

기존 리프레시 토큰은 갱신 후 즉시 무효화됩니다. 응답으로 받은 새로운 리프레시 토큰을 안전하게 저장하세요.

사용 시나리오​

액세스 토큰 만료 감지
        ↓
리프레시 토큰으로 갱신 API 호출
        ↓
새 토큰 쌍 수신 및 저장
        ↓
새 액세스 토큰으로 API 요청 재시도

오류 코드 참조​

코드메시지설명
2000SERVER_ERROR서버 내부 오류
2003REFRESH_TOKEN_EXPIRED리프레시 토큰 만료
2051INVALID_TOKEN토큰이 유효하지 않음

변경 이력​

버전날짜작성자변경 내용
0.1.02025-12-18Claude Code최초 문서 작성