버전: 0.68.0

토큰 갱신 API

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

토큰 갱신

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

HTTP Method: POST
Path: /de/v1/auth/token/refresh
인증: 없음 (이 API는 리프레시 토큰 자체를 인증 수단으로 사용)

Headers

Header	Type	Description	Required
`Content-Type`	`application/json`	요청 본문 형식을 지정합니다.	Yes

Request Body (`RefreshTokenDto`)

{
  "refreshToken": "your_refresh_token_here"
}

필드	타입	설명	필수 (Yes/No)
`refreshToken`	string	사용자가 보유한 유효한 리프레시 토큰	Yes

Responses

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

200 OK - 토큰 갱신 성공

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

{
  "tokens": [
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...new_access_token",
      "type": "ACCESS_TOKEN",
      "expiresIn": 1800,
      "issuedAt": 1714524000000
    },
    {
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...new_refresh_token",
      "type": "REFRESH_TOKEN",
      "expiresIn": 604800,
      "issuedAt": 1714524000000
    }
  ]
}

필드	타입	설명	예시	필수 (Yes/No)
`tokens`	array	인증 토큰 정보 배열 (`TokenResponseDto[]`). 정확히 2개의 토큰(새로운 access token과 새로운 refresh token)을 포함해야 합니다.		Yes
`tokens[].token`	string	토큰 값	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`	Yes
`tokens[].type`	string	토큰 타입 (TokenType 참조)	`ACCESS_TOKEN` 또는 `REFRESH_TOKEN`	Yes
`tokens[].expiresIn`	number	토큰 만료 시간 (초, Kotlin: `Int`, Swift: `Int`)	`1800`	Yes
`tokens[].issuedAt`	number	토큰 발급 시간 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)	`1714524000000`	Yes

401 Unauthorized - 인증 실패

예시: 유효하지 않은 토큰 (일반)

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

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

예시: 리프레시 토큰 만료

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

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

500 Internal Server Error - 서버 내부 오류

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

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

설명

이 API는 UserAuthController의 refreshToken 메서드와 AuthService의 refreshToken 메서드 로직을 기반으로 합니다.
주요 검증 단계 (서비스 로직 내 예상):
1. 제공된 refreshToken 문자열의 유효성 검사 (존재 여부, 형식 등).
2. 데이터베이스에서 해당 리프레시 토큰 조회.
3. 토큰의 상태(TokenStatus)가 ACTIVE인지 확인. 만약 REVOKED 또는 EXPIRED 상태라면 에러 반환.
4. 토큰이 만료되지 않았는지 확인 (만료 시간이 현재 시간 이전인지).
5. 연관된 사용자 정보 확인.
6. 새로운 액세스 토큰과 리프레시 토큰 쌍 생성.
7. 기존 리프레시 토큰은 상태를 REVOKED 또는 EXPIRED로 변경하거나 삭제 (보안 정책에 따라 다름). 새로운 리프레시 토큰 저장.
성공적인 토큰 갱신 시, 새로운 액세스 토큰과 새로운 리프레시 토큰이 발급됩니다. 클라이언트는 이 새 토큰들을 사용하여 인증을 계속해야 합니다.
만약 HttpException이 아닌 다른 에러가 발생하면 UnauthorizedException으로 처리됩니다.

RefreshTokenResponseDto 상세

RefreshTokenResponseDto는 LoginResponseDto의 tokens 부분과 유사한 구조를 가집니다.

필드	타입	설명	필수
`tokens`	`TokenResponseDto[]`	새로운 인증 토큰 정보 배열 (Access Token, Refresh Token 각 1개씩)	Yes

TokenResponseDto 상세

RefreshTokenResponseDto의 tokens 배열에 있는 각 객체에 대한 상세 설명입니다. 이 배열은 반드시 정확히 2개의 토큰(새로운 access token과 새로운 refresh token)을 포함해야 합니다.

필드	타입	설명	예시	필수
`token`	string	토큰 값	`eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`	Yes
`type`	string	토큰 타입 (TokenType 참조)	`ACCESS_TOKEN` 또는 `REFRESH_TOKEN`	Yes
`expiresIn`	number	토큰 만료 시간 (초, Kotlin: `Int`, Swift: `Int`)	`1800`	Yes
`issuedAt`	number	토큰 발급 시간 (Unix timestamp in milliseconds, Kotlin: `Long`, Swift: `Int64`)	`1714524000000`	Yes

변경 이력

버전	날짜	작성자	변경 내용
0.1.0	2025-05-30	elizabeth@weltcorp.com	최초 문서 작성
0.2.0	2025-06-13	elizabeth@weltcorp.com	오류 코드 표준화 (2002 → 2051 INVALID_TOKEN)

토큰 갱신​

Headers​

Request Body (RefreshTokenDto)​

Responses​

설명​

RefreshTokenResponseDto 상세​

TokenResponseDto 상세​

변경 이력​