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 feature 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 with any method except the authenticateWithToken:andBlock:, authenticateWithToken:andDelegate:andCallback:, authenticateWithToken:andExpiresAt:andBlock:, authenticateWithTokenSynchronous:andError: and authenticateWithTokenSynchronous:andExpiresAt:andError:). If the login succeeds, the refresh token will be auto-saved together with other user credentials.
  4. This is all! Kii SDK will refresh the expired token automatically when needed.

Use the method described in Login with the Auto-Saved Credentials for serializing the refresh token.

If you want to check if the token refresh is working, you can do so with the accessToken method described in Login by Manually Specifying an Access Token.

Handling token refresh errors

When using the refresh token feature, you need to handle the case when the token refresh failed. The access token refresh is automatically executed by the SDK, and thus the application normally does not need to be aware of the refreshing. If an API that accessed the server returns a specific exception, however, your application needs to handle the re-login process.

Refreshing an access token will succeed in most cases, but it could fail in some rare cases. For example, if the application fails to receive a new refresh token issued by the server due to a network error, the SDK can no longer refresh the access token because the old refresh token is invalidated at that time.

If the SDK fails to refresh the access token, it will throw the KiiError.codeRefreshTokenFailed() exception. The user will be in the logout state, and your application will need to ask the user to login with their username and password.