실전 토큰 라이프사이클

모든 OAuth 플로 가이드에서 refresh_token을 언급하지만, 여러 요청·워커·여러 날에 걸쳐 계속 실행되는 장기 실행 연동에는 “만료되면 토큰을 교체한다” 이상의 것이 필요합니다. 이 페이지에서는 실제 토큰 수명, 여러 워커 간 토큰 캐싱, 갱신 시점, 그리고 토큰이 원래 만료되기 전에 무효화될 수 있는 요인을 다룹니다.

---

플로별 토큰 수명

액세스 토큰의 수명은 모든 플로에서 동일한 고정 기간입니다. 리프레시 토큰은 그렇지 않으며, 어떤 OAuth 플로가 발급했는지에 따라 달라집니다.

플로	액세스 토큰 TTL	리프레시 토큰 TTL
Client Credentials 플로	약 1시간	약 30일
Native Application 플로(PKCE, 루프백 리디렉션)	약 1시간	고정 만료 시점 없음: 로테이션으로 교체되거나 취소될 때까지 유효
Authorization Code + Custom Redirect 플로	약 1시간	고정 만료 시점 없음: 로테이션으로 교체되거나 취소될 때까지 유효

참고

두 Authorization Code 플로 모두 세션 시계가 전혀 없는 리프레시 토큰을 발급합니다. 그렇다고 무한정 사용되지 않은 채 남아 있는 것은 아닙니다. 이는 일회용 토큰으로, 갱신할 때마다 교체됩니다(아래 동시 갱신 경합 참고). 그리고 그랜트가 취소되면 즉시 작동을 멈춥니다.

요청마다 새로 발급하지 말고 토큰을 캐시하세요

API 호출마다, 혹은 각 워커 프로세스에서 독립적으로 새 액세스 토큰을 요청해도 동작은 하지만, 이미 약 1시간 동안 유효한 토큰을 위해 요청마다 왕복을 낭비하게 됩니다. 토큰을 한 번 요청하고, 이를 발급한 자격 증명을 키로 캐시한 뒤(단일 프로세스라면 메모리에, 워커 플릿이라면 Redis 같은 공유 스토어에), 만료가 임박할 때까지 모든 요청에 캐시된 토큰을 사용하세요.

이는 리프레시 토큰에도 중요합니다. 독립적으로 교환하는 프로세스가 적을수록 아래에서 설명하는 경합 상태를 겪을 가능성이 줄어듭니다.

401뿐 아니라 만료 시점에 갱신하세요

액세스 토큰의 TTL은 고정되어 있고 미리 알 수 있으므로, 선제적으로 갱신하세요. 토큰을 얻은 시점을 추적하거나(또는 exp 클레임을 디코딩하여) 만료 직전에 새 토큰을 요청하고, 요청이 먼저 실패하기를 기다리지 마세요.

그래도 폴백으로 실패한 요청을 처리하되, 받은 오류에 따라 구분하세요.

• not_authenticated가 포함된 401: 요청에 사용 가능한 베어러 토큰이 전혀 없었습니다. 이는 클라이언트 측 버그(누락되거나 잘못된 형식의 Authorization 헤더)이며, 갱신 신호가 아닙니다.
• invalid_token이 포함된 401: 토큰의 서명 또는 만료 검사가 실패했습니다. 갱신 후 한 번 재시도하세요.
• 403: 절대 토큰 문제가 아닙니다. 토큰은 유효하지만, 호출자가 해당 작업에 필요한 스코프, 콘텐츠 접근 권한, 또는 역할을 가지고 있지 않습니다. 갱신해도 도움이 되지 않습니다. 각 코드에 대한 전체 설명은 오류 코드: 속도 제한, 인증, 접근 제어를 참고하세요.

동시 갱신 경합

리프레시 토큰은 일회용입니다. grant_type=refresh_token으로 교환하면 해당 리프레시 토큰이 무효화되고, 새 액세스 토큰과 새 리프레시 토큰이 함께 발급됩니다. 여러 워커가 캐시된 동일한 리프레시 토큰을 공유하고 그중 둘이 거의 동시에 갱신을 시도하면, 한쪽 교환만 성공합니다. 다른 쪽은 “이미 사용됨”과 구분되는 오류가 아니라 일반적인 401을 받습니다.

주의

공유된 리프레시 토큰에 대해 모든 워커가 독립적으로 갱신하게 두지 마세요. 갱신 호출의 단일 소유자를 지정하고(갱신 경로에 락을 걸거나 전용 갱신 루틴을 사용), 나머지 워커는 스스로 갱신하는 대신 공유 캐시에서 결과 액세스 토큰을 읽도록 하세요.

토큰을 조기에 무효화하는 요인

아래 이벤트 중 어느 것도 유효한 액세스 토큰을 즉시 취소하지 않습니다. 각 이벤트는 오직 새로운 무언가(새 토큰 요청 또는 다음 갱신)만 차단하며, 이미 가지고 있는 액세스 토큰은 자체 TTL이 다할 때까지 계속 작동합니다.

트리거	영향
OAuth 애플리케이션의 클라이언트 시크릿이 교체됨	이전 시크릿을 사용한 새 토큰 또는 갱신 요청은 즉시 거부됩니다. 이미 발급된 액세스 토큰은 영향을 받지 않고 자연 만료될 때까지 계속 작동합니다.
OAuth 애플리케이션 또는 그 서비스 사용자가 삭제됨	해당 애플리케이션에 대한 새 토큰 발급을 차단합니다. 이미 발급된 토큰은 능동적으로 취소되지 않습니다.
OAuth 애플리케이션의 스코프가 변경됨	이미 발급된 액세스 토큰은 남은 수명 동안 원래 스코프를 유지합니다. 토큰은 다음 갱신 또는 재발급 시에만 새 스코프를 적용받습니다.
그랜트가 명시적으로 취소됨	다음 갱신 시도를 즉시 차단합니다. 여전히 유효한 액세스 토큰은 강제로 만료되지 않고 자연 만료될 때까지 계속 작동합니다.

참고

이 이벤트들 중 어느 것도 이미 발급된 토큰을 건드리지 않으므로, 이후의 실질적인 노출 시간은 리프레시 토큰이 아니라 액세스 토큰 자체의 TTL(약 1시간)입니다. 이 시간을 즉시 0으로 줄이려면 그랜트 취소와 시크릿 교체를 함께 수행한 뒤, 액세스 토큰 TTL 한 번이 지날 때까지 해당 연동을 미승인 상태로 취급하세요.

다음 단계

• 오류 코드: 401과 403 응답에 대한 전체 설명
• Client Credentials 플로, Native Application 플로, 또는 Authorization Code + Custom Redirect 플로: 첫 토큰을 발급받는 방법