토큰(접근,갱신)만료 시 처리절차
접근토큰과 갱신토큰의 유효시간은 각각 아래와 같습니다.
| 토큰명 | 내용 | 유효시간(초) |
|---|---|---|
| 접근토큰(access_token) | 유저 엑세스 토큰 값 | 7,776,000초 (90일) |
| 갱신토큰(refresh_token) | 유저 리프레시 토큰 | 투자자문·일임 계약기간 내에서 유효 |
사용자가 투자자문·일임 계약을 체결한 경우, 해당 계약의 유효기간에 따라 오픈API 이용기간이 연장되며, 갱신토큰 역시 계약기간 내에서 유효합니다.
따라서 토큰 유효기간이 만료되었을 경우 아래와 같이 갱신/재발급하여야 합니다.
- 접근토큰(access_token) 만기시
- 토큰 만기로 인한 거부 메시지 수신됨.
- 접근토큰갱신(/oauth2/tokenP)을 호출하여 갱신토큰(refresh_token)으로 접근토큰(access_token) 갱신을 요청
- 접근토큰 재발급은 제휴사가 수행 (고객 오퍼레이션 없음)
- 갱신토큰(refresh_token) 만기시 (※ 투자자문·일임 제휴사 미해당)
- 갱신토큰은 접근토큰 갱신시에만 사용.
- 접근토큰 갱신을 시도해야 갱신토큰 유효여부(만기가 지났는지) 알수 있음. (혹은 제휴사가 최초 발급 시 갱신토큰 유효기간 저장, ex. "refresh_token_token_expired": "2025-08-15 06:35:25")
- 갱신토큰(refresh_token) 재발급(=API재신청)은 반드시 고객이 오퍼레이션 해야함
- 하위 문서 '갱신토큰 재발급 방법' 참고
접근토큰 갱신 방법
접근토큰(access_token) 만기시, 제휴사는 접근토큰갱신(/oauth2/tokenP)을 호출하여 갱신토큰(refresh_token)으로 접근토큰(access_token) 갱신을 요청할 수 있습니다. (고객 오퍼레이션 없음)
- 접근토큰갱신 API는 "기존계좌 API신청" 문서 확인 바랍니다.
접근토큰 유효기간을 제휴사에서 관리하는 방법은 아래 2가지 방법이 있습니다.
- 1. 접근토큰 갱신을 주기적으로 수행 (예를들면 계약체결일 또는 API발급일로부터 매 1개월단위)
- 2. 접근토큰 만기일을 저장하고 있다가 접근토큰 만기 도래전에 갱신 수행 (접근토큰 갱신 횟수는 제한없음)
갱신토큰 재발급 방법
갱신토큰(refresh_token) 만기 시, 갱신토큰(refresh_token) 재발급(=API재신청)은 반드시 고객이 오퍼레이션 해야 합니다.
※ 사용자가 투자자문·일임 계약을 체결한 경우, 해당 계약의 유효기간에 따라 오픈API 이용기간이 연장되며, 갱신토큰 역시 계약기간 내에서 유효합니다. 따라서 고객과 자문·일임 계약을 체결한 제휴사는, 갱신토큰이 계약기간 동안 자동으로 유효하므로 아래 갱신토큰 재발급 프로세스를 구현할 필요가 없습니다.
갱신토큰 유효기간을 제휴사에서 관리하는 방법은 사전/사후 여부에 따라 아래 2가지 방법이 있습니다.
1. 사전관리방법 (갱신토큰 만기전 관리)
갱신토큰(refresh_token) 발급은 고객 오퍼레이션(API신청 웹뷰)이 필요하므로 제휴사가 자체적으로 갱신토큰 만기일 관리 (제휴사가 최초 발급 시 유효기간 저장, ex. "refresh_token_token_expired": "2025-08-15 06:35:25")하고 만기일-1개월 정도부터 고객에게 push, sms 등의 방법으로 API재신청 안내
2. 사후관리방법 (갱신토큰 만기후 관리)
제휴사 앱에서 고객이 자문 승인 오퍼레이션시 API TR 중 조회성 TR 발송 후 토큰만기로 인한 거부 발생시고객에게 API 재신청 안내 및 진행 유도
갱신토큰 만료 시 처리 절차 (인가코드발급요청(/oauth2/authorizeP) 호출 시 유의사항)
갱신토큰이 만료되어 고객 API신청(=오퍼레이션) 요청할 때 인가코드요청(/oauth2/authorizeP) 'reregist_yn'을 Y로 설정하여 호출하여 자문계약 불가요건에 상관없이 토큰 재발급이 가능
재신청 시에는 고객 웹뷰에 계좌 지정하여 토큰 재발급 진행해야 하며, 아래 3가지 설정값 입력이 필수
- 필수입력값
- reregist_yn : Y
- acctno : ex) 1234567801
- thco_ivst_etrs_bzep_cd : ex) 001878