Refreshing the Access Token

Kii Cloud supports the OAuth 2.0 refresh token. By leveraging the refresh token, you can set the short expiration period on the access token without harming the usability.

The access token is attached to all requests sent to Kii Cloud via a network, so it is exposed to the public to some extent. Shortening the expiration period of the token alleviates this problem, but it would harm the usability of your application if it frequently asks users to type in their username and password. The refresh token will solve the issue by internally re-issuing the access token.

The following figure illustrates how the refresh token works. The number of times the refresh token is sent via the network is much smaller than that of the access token, making it safer from the token leakage risk point of view.

Note that the figure shows the simplified flow; more information is actually auto-saved by the SDK.

The client SDK will automatically refresh the access token if the feature is enabled. When you execute an API of the SDK and the remaining expiration time of the access token is less than 5 minutes, the SDK will automatically start a process for getting a new access token. If you are using the REST API, you need to implement a refreshing logic that is equivalent to that of the SDK.

The list below summarizes the detailed specification of the refresh token feature.

  • You can get the refresh token together with the access token when the user login is processed.
  • The access token and refresh token are re-issued when the refresh is executed. The old access token and refresh token will be invalidated. The refresh token is only usable once.
  • You can use the refresh token feature when a user is authenticated with their email address or phone number. You cannot use the refresh token feature if a user is logged in as a pseudo user. You also cannot use the feature for the thing's persistent token.
  • If a user logs in multiple times with a method such as entering the username and password, issued access tokens do not get affected by any of the other refreshed access tokens. For example, when an access token A1 is refreshed to A2, an access token B that was issued by another login remains valid. The access token B is refreshed at its own intervals.
  • A refresh token basically will not expire, but it could be disabled in some cases, like when a user changes his password or during system maintenance. We recommend you not to implement your app with an assumption that the refresh token will never expire. We recommend you to implement a logic for re-login.
  • A refresh token is invalidated when the user is disabled.
  • If an access token is expired when you execute an API, you will be able to execute the API with a new access token if a refresh token is valid.

Using the refresh token

Here are the steps for using the refresh token.

  1. Enable the refresh token on the developer portal. Please check Setting the expiration on the developer portal for the details.
  2. Set the expiration period of the access token. We recommend you to set both the default and upper limit of the expiration period.
  3. Execute the login. If the login is successful, you will get an access token, refresh token and the expiration period of the access token as a response.
  4. Execute other APIs with the access token.
  5. Execute the refresh token API before the access token expires. You will get a new access token, refresh token and the expiration period. From that point forward, repeat the step 4 and 5.

Refreshing the access token

If you set the "Enable Refresh Token" option ON on the developer portal, a refresh token will be set in the "refresh_token" field in the login response as follows:

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Mon, 14 May 2012 22:52:52 GMT
<
{
  "id" : {USER_ID},
  "access_token" : {ACCESS_TOKEN},
  "refresh_token" : {REFRESH_TOKEN}
  "expires_in" : 864000
}

Make sure to keep the refresh token in a secure place. Anyone who has the refresh token will be able to access Kii Cloud with the token holder's privilege.

Here is an example of refreshing an access token.

This example assumes that you've set the default expiration period on the developer portal. You can also specify the expiration period dynamically by setting the expiration date (UNIX time in msec, UTC) in the "expires_at" field.

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "refresh_token",
        "refresh_token": "{REFRESH_TOKEN}"
      }'

You refresh an access token with Basic Authentication. Replace {BASE64_ENCODED_APPID_AND_APPKEY} with a Base64-encoded string of concatenated AppID and an arbitrary value with a colon (:) in between the two values.

If the token refresh succeeds, you will get the following response. The new access token and refresh token are returned in the "access_token" and "refresh_token" fields, respectively. The expiration period of the access token is set in the expired_in" field.

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Type: application/json
< Transfer-Encoding: chunked
< Date: Mon, 14 May 2012 22:52:52 GMT
<
{
  "id" : {USER_ID},
  "access_token" : {ACCESS_TOKEN},
  "refresh_token" : {REFRESH_TOKEN}
  "expires_in" : 864000
}

When the server accepts the refresh token request and executes the refresh, the old access token and the refresh token will be invalidated regardless of if a client receives the new access token and refresh token. If the client fails to receive a new access token and refresh token for some reasons (e.g. network error), you need to execute the login again with a username and password.