REST API Access Token

Iamport REST API service provides the ability to query the payment details of your merchant, process refund requests, and handle escrow payments. However, since it deals with the merchant’s private resource, it can be accessed after the ownership of the resource is authenticated.

At this point, an access token can be issued and included in the API request to prove the ownership of the merchant and access to private resources.

What is Access Token?

Iamport REST API uses a token-based authentication, The authentication process is performed by verifying that all requests to Iamport REST API accessing the private resource contain a token and the token is valid.

The token used in the process is called an access token.

Issuing a Token

The token can be acquired through the REST API in Iamport that issues tokens. The token can be issued from https:\//api.iamport.kr/users/getToken.

Issuing a token on the server side

It is insecure to perform the process of issuing the access token on the client side as the REST API Key and REST API Secret can be exposed. The request to issue the token must be performed on the server side.

1Request

To issue an access token, the request to https:\//api.iamport.kr/users/getToken should be made.

curl

Node.js

  curl -H "Content-Type: application/json" POST -d '{"imp_key": "REST API키", "imp_secret":"REST API Secret"}' https://api.iamport.kr/users/getToken

The POST request is created including imp_key: "REST API key" and imp_secret: "REST API Secret" for https:\//api.iamport.kr/users/getToken.

Check REST API Key & REST API Secret

REST API key and REST API secret of your account can be found from the My Info tab of System Configuration page in Iamport Admin Dashboard.

2Acquire a Token

When authentication is completed through the REST API key and REST API Secret included in the request, the access token included in the response can be acquired.

JSON

  {
    "code": 0,
    "message": null,
    "response":{
      "access_token": "a9ace025c90c0da2161075da6ddd3492a2fca776",
      "now": 1512446940,
      "expired_at": 1512448740,
    },
  }

The value of access_token attribute in the response data is the access token. The expired_at attribute means the expiration time of the token and is displayed as UNIX timestamp (KST). The access token must be reissued used when the expiration time has passed. The value of now property indicates the current time of Iamport REST API server. The value can be used to find a time error in merchant servers.

Standard NTP server

Iamport REST API server uses Google Public NTP to synchronize with a standard time.

Using a Token

Once the access token has been successfully issued, you can use it to authenticate the request to Iamport REST API.

It is included in the HTTP request header as Authorization: Bearer <token> format as Iamport REST API uses Bearer authentication method. It can be specified as follow: Authorization: Bearer a9ace025c90c0da2161075da6ddd3492a2fca776.

The following is an example of API request request for a detailed transaction history.

curl

Node.js

  curl -H "Content-Type: application/json" -H "Authorization: Bearer a9ace025c90c0da2161075da6ddd3492a2fca776" https://api.iamport.kr/payments/imp_448280090638

The access token issued in Bearer form was used in Authorization header for the request of https:\//api.iamport.kr/payments/{imp_uid}.

Reissue and Reuse of Access Token.

When an access token is issued, expiration is set to 30 minutes from the token issuance time. Tokens are only valid for 30 minutes of expiration time, so the token cannot be used once the expiration time has passed. If you make an API request using the expired token, 401 Unauthorized response is returned.

1Issuance a token after the expiration time (Reissue)

When obtaining an access token by creating a request for https:\//api.iamport.kr/users/getToken, the existing access token may not exist or it may be already expired. In this case, Iamport REST API server responses with a newly created access token. The expiration time of the new access token is 30 minutes from the issuance.

2Issuance a token before the expiration time (Reuse)

When obtaining an access token by creating a request for https:\//api.iamport.kr/users/getToken, the existing access token can still be valid (it has not reached the expiration time). In this case, Iamport REST API server responses with the existing access token.

The expiration time (expired_at) of the token for the request before the expiration time stays the same as the expiration time of the first issuance. However, when the request is made within 1 minute from the expiration time of the existing access token (from 1 minute before to the expiration time), the existing expiration time is extended by 5 minutes.

The extension of expiration time by 5 minutes

The reuse of access tokens and the extension of the expiration time by 5 minutes are designed considering the following realistic merchant environment.

A situation where multiple web servers in merchants are making REST API calls to /users/getToken competitively at the same time
A situation where multiple web servers in a merchant are making REST API calls but the time is not in sync.