REST API 액세스 토큰(access token)

아임포트 REST API서비스는 여러분의 가맹점의 결제 상세정보를 조회하거나 환불 요청 또는 에스크로 결제를 처리할 수 있는 기능을 제공합니다. 하지만 이는 가맹점의 사적 리소스(private resource)를 다루기 때문에 해당 리소스의 소유권을 인증한 후 접근할 수 있습니다.

이때 액세스 토큰(access token)을 발급받고 API 요청에 포함하여 가맹점의 소유권을 증명하고 사적 리소스(private resource)에 접근할 수 있습니다.

액세스 토큰(access token)이란?

아임포트 REST API서비스는 토큰 기반 인증을 사용합니다. 사적 리소스(private resource)에 접근하는 아임포트 REST API에 대한 모든 요청에 토큰이 포함되어 있는지, 또 해당 토큰이 유효한지의 여부를 검증함으로써 인증 절차를 수행합니다.

이때 사용하는 토큰을 액세스 토큰(access token)이라 부릅니다.

토큰 발급받기

아임포트 REST API 중 액세스 토큰(access token)을 발급하는 API를 활용하여 토큰을 발급받습니다. https:\//api.iamport.kr/users/getToken을 통해 액세스 토큰(access token)을 발급받을 수 있습니다.

서버사이드에서 토큰 발급하기

액세스 토큰 발급 과정을 클라이언트에서 수행하면REST API키와 REST API Secret이 노출되어 보안상 안전하지 않기 때문에 토큰 발급 요청은 반드시 서버사이드에서 수행해야합니다.
1요청하기
액세스 토큰(access token)의 발급을 위해 https:\//api.iamport.kr/users/getToken에 대해 요청을 생성합니다.
  curl -H "Content-Type: application/json" POST -d '{"imp_key": "REST API키", "imp_secret":"REST API Secret"}' https://api.iamport.kr/users/getToken
https:\//api.iamport.kr/users/getToken에 대해 imp_key: "REST API 키", imp_secret: "REST API secret"를 포함하여 POST요청을 생성합니다.

REST API 키 & REST API secret 확인하기

여러분의 계정의 REST API 키와 REST API secret은 아임포트 관리자 대시보드의 시스템설정 페이지의 내정보 탭에서 확인할 수 있습니다.
2토큰 획득하기
요청에 포함한 REST API 키와 REST API Secret을 통해 인증이 완료되면 응답에 포함된 액세스 토큰(access token)을 획득할 수 있습니다.
  {
    "code": 0,
    "message": null,
    "response":{
      "access_token": "a9ace025c90c0da2161075da6ddd3492a2fca776",
      "now": 1512446940,
      "expired_at": 1512448740,
    },
  }
응답 데이터의 access_token속성의 값이 액세스 토큰(access token)입니다. expired_at속성은 토큰의 만료기한을 의미하며 unix timestamp로 표현됩니다(KST 기준). 발행된 액세스 토큰은 만료기한이 지난 경우 새로운 토큰을 발급받아 사용해야 합니다. now속성의 값은 아임포트 REST API 서버의 현재 시각을 나타내며, 해당 값으로 가맹점 서버와의 시간 오차를 파악할 수 있습니다.

기준 NTP서버

아임포트 REST API 서버는 Google Public NTP를 이용하여 기준시간과 동기화하고 있습니다.

토큰 사용하기

액세스 토큰(access token)을 성공적으로 발급받았으면 해당 토큰을 사용하여 아임포트 REST API요청에 대해 인증할 수 있습니다.

아임포트 REST API는 Bearer 인증 방식을 사용하기 때문에 Authorization: Bearer <token>형식으로 HTTP 요청 헤더에 포함합니다. Authorization: Bearer a9ace025c90c0da2161075da6ddd3492a2fca776와 같은 형식으로 작성할 수 있습니다.

다음은 거래 내역 상세 조회 API에 대한 요청 예시 입니다.
  curl -H "Content-Type: application/json" -H "Authorization: Bearer a9ace025c90c0da2161075da6ddd3492a2fca776" https://api.iamport.kr/payments/imp_448280090638
https:\//api.iamport.kr/payments/{imp_uid}에 대한 요청에서 Authorization헤더에 Bearer타입으로 발행된 액세스 토큰을 작성했습니다.

액세스 토큰(access token)의 재발행과 재사용

액세스 토큰이 발행될 때 토큰의 발행 시간으로부터 30분 후로 만료기한이 정해집니다. 토큰은 만료기한이 되기 전 30분 동안만 유효하기 때문에 만료기한이 지나면 해당 토큰은 사용할 수 없습니다. 만료된 토큰을 사용하여 API 요청을 생성하면 401 Unauthorized응답을 받게됩니다.
1만료기한 이후 토큰 발급(재발행)
https:\//api.iamport.kr/users/getToken에 대해 요청을 생성하여 액세스 토큰(access token)을 발급받으려 할 때, 기존에 발행된 액세스 토큰이 없거나 만료기한이 지난 상태일 경우에는 아임포트 REST API서버는 새로운 액세스 토큰을 발행해 응답합니다. 이때 발행된 액세스 토큰의 만료기한은 발행 시간으로부터 30분 후 입니다.
2만료기한 이전 토큰 발급(재사용)
https:\//api.iamport.kr/users/getToken에 대해 요청을 생성하여 액세스 토큰(access token)을 발급받으려 할 때, 이전에 발행한 액세스 토큰이 아직 유효한 상태(토큰의 만료기한이 지나지 않은 상태)라면 아임포트 REST API서버는 기존에 발행한 액세스 토큰을 응답합니다.

만료기한 이전 요청에 대한 토큰의 만료기한(expired_at)은 기존 토큰 발급시의 만료 기한과 동일합니다. 하지만 예외적으로 기존 액세스 토큰의 만료기한으로부터 1분 이내(_만료기한 1분 전부터 만료기한까지_)에 요청을 생성했을 때에는 기존의 만료 기한이 5분 연장됩니다.

만료기한 5분 연장

액세스 토큰(access token)의 재사용과 만료기한 5분 연장 동작방식은 다음과 같은 현실적인 가맹점의 환경을 고려하여 설계되었습니다.
  • REST API에 대해 요청을 생성하는 가맹점의 웹서버가 여러 대이며, 동시에 경쟁적으로 /users/getToken를 호출하는 상황
  • REST API에 대해 요청을 생성하는 가맹점의 웹서버가 여러 대이며, 시간 동기화가 되어있지 않은 상황