토큰(접근,갱신)만료 시 처리절차
접근토큰과 갱신토큰의 유효시간은 각각 아래와 같습니다.
| 토큰명 | 내용 | 유효시간(초) |
|---|---|---|
| 접근토큰(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재신청)은 반드시 고객이 오퍼레이션 해야 합니다.
갱신토큰 유효기간을 제휴사에서 관리하는 방법은 사전/사후 여부에 따라 아래 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