Admin Features

The REST APIs support features mainly for app administrators. With those features, you can maintain and configure your application.

Getting an app admin token

To access admin features, you will need to provide an application admin token. Kii Cloud will determine if you have the right to access these APIs by checking the token.

To get the app admin token, you need to provide your application's ClientID and ClientSecret. You can find these values on the developer portal.

You should never embed the ClientID and the ClientSecret in your application. If you need to use them, consider to use server extension.

You can also use the app admin token when calling non-admin features. In this case, the admin token will act as a "super user" token; you will be able to leverage any features. In this case, make sure that you do not use "/me" literal in Resource URL.

Once you get the ClientID and ClientSecret, you are ready to get the app admin token as follows:

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "Content-Type: application/json" \
  "{APP_ID}/oauth2/token" \
  -d '{
        "grant_type": "client_credentials",
        "client_id": "{CLIENT_ID}",
        "client_secret": "{CLIENT_SECRET}",
        "expiresAt": {EXPIRED_TIME}

You get an app administrator 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.

Put your ClientID and ClientSecret in {CLIENT_ID} and {CLIENT_SECRET}, respectively.

You can also specify when the app admin 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 app admin token will never expire.

We recommend you to set the expiration time with the expiresAt parameter when getting an app admin token. If the app admin token is leaked, all application data become vulnerable to misuse and abuse. Setting a short expiration time on the app admin token will alleviate this risk.

If the given ClientID and ClientSecret are correct, Kii Cloud will return a response as shown; the value set in "access_token" and "expires_in" are the app admin token and time span in seconds of how long the token will be valid, respectively.

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Mon, 14 May 2012 17:36:41 GMT

  "id" : "f00685f32fde76290b4bcdc2a36b9b73",
  "access_token" : "99026627-b41e-478d-b497-5ba418e7f78c",
  "expires_in" : 600,
  "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 (UTC) 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.