Logging in

Once users are registered with your application (after completing the user verification process if required) they will be able to log in with their username, phone number or email address.

Logging in with the REST API is equivalent to requesting an access token by providing the user's username and password. Once the access token is retrieved, it can be used throughout the REST API calls that require authentication. See Logging in and Using an Access Token to learn more.

Logging in

Here is a request for retrieving an access token:

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": "password",
        "username": "user_123456",
        "password": "123ABC"
      }'

You log in 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.

You can send a request with one of the following "username" values:

• username
• international phone number
• email address
• EMAIL: email address
• PHONE: international phone number (e.g. PHONE:+819012341234)
• PHONE: 2-letter country code-local phone number (e.g. PHONE:JP-9012341234)

You can also specify when the access token will expire by setting the "expiresAt" parameter. Please specify the expiration time in UNIX time (msec) in UTC. If no expiration time is specified, the access token will never expire.

Kii Cloud will return a response as shown below; the user's token is returned as "access_token" along with this user's User ID and the duration of the token (sec).

< 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},
  "expires_in" : 2147483647,
  "token_type" : "bearer"
}

Note that the expiration time in the request (expiresAt) and in the response (expired_in) hold a value in different formats. The expiresAt parameter holds a date while the expired_in parameter holds the number of seconds from the current time. For example, if you requested an access token at the noon of December 1st, 2015 and the token should have expired at the noon of the next day, you would have specified "expiresAt" : 1449057600000 and the response would have had a value around 86400 (24 hours x 60 minutes x 60 seconds) in the expires_in parameter.

If you are going to store an access token, please make sure to store it in a secure place. It should not be accessible by other applications. If a malicious application gets the access token, it will gain privileges to access Kii Cloud as the owner of this token.

If a user's password is changed, the user's access token becomes invalid. Authenticate the user with their username and password so as to get a new access token.
Also, if a user is disabled, the user's access token becomes invalid.

There is no way to log out a user. The user is virtually logged out by removing the access token from the client memory (this also applies to the client SDKs). If a user is disabled, all access tokens that are bound to this user will be invalided.

Investigating failed logins

You will get the HTTP status 400 if the specified user does not exist or if the password is invalid. The HTTP status 400 is also returned if the specified user is currently disabled.

For security reasons, the REST API cannot determine which is the cause of the exception. On the other hand, the app administrator can identify the error cause by checking the developer log.