アプリ管理者向け機能

REST API は、アプリの挙動設定などを行うアプリ管理者向け機能を提供しています。

アプリ管理者トークンの取得

アプリ管理者トークンは、アプリ管理者向けではない通常の機能をリクエストする際にも利用可能です。この場合、トークンは「スーパーユーザートークン」として解釈され、全ての機能が利用可能になります。この際、Resource URL において "/me" リテラルを使わないよう注意してください。

アプリ管理者向け機能を利用するためには、アプリ管理者トークンを送信する必要があります。Kii Cloud は、このアプリ管理者トークンを元に、リクエスト送信者が正しい権限を有しているかを確認します。

アプリ管理者トークンは、アプリケーションの ClientID と ClientSecret を提示することで取得できます。これらの値は 開発者ポータル で確認できます。

なお、ClientID と ClientSecret を埋め込んだアプリをユーザーに配布するのはセキュリティリスクがあります。これらが必要な場合は サーバ機能拡張 の利用を検討してください。

以下に、アプリ管理者トークンを取得する例を挙げます。

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": "client_credentials",
        "client_id": "{CLIENT_ID}",
        "client_secret": "{CLIENT_SECRET}",
        "expiresAt": {EXPIRED_TIME}
      }'

匿名ユーザートークンの取得は Basic 認証 を使って行います。{BASE64_ENCODED_APPID_AND_APPKEY} には AppID と AppKey をコロン(:) で連結した文字列を Base64 エンコードしたものを入れてください。

{CLIENT_ID}{CLIENT_SECRET} には、それぞれアプリケーションの ClientID と ClientSecret の値を入れてください。

さらに expiresAt パラメータを指定することでアプリ管理者トークンの有効期限(UNIX 時間・ミリ秒、UTC)が設定できます。有効期限の設定がない場合は、アプリ管理者トークンは永久的に有効となります。

アプリ管理者トークンの取得の際は、expiresAt パラメータを常に指定することをお勧めします。アプリ管理者トークンの漏洩は、アプリ内の全データの不正アクセスにつながりますが、有効期限が短い値で設定されているとそのリスクを軽減できます。

正しい ClientID と ClientSecret が渡されると、Kii Cloud は次のように応答します。応答中の "access_token" がアプリ管理者トークンです。また "expires_in" は、このアプリ管理者トークンが有効な時間(秒)です。

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"
}

リクエストの "expiresAt" とレスポンスの "expired_in" は表現形式が異なる点にご注意ください。"expiresAt" は日付での指定ですが、"expired_in" は現在時刻からの残り秒数です。たとえば、2015 年 12 月 1 日の正午(UTC)に翌日の正午までのトークンを取得するとき、"expiresAt" : 1449057600000 の指定により、"expires_in" : 86400 前後の値(24 時間× 60 分× 60 秒前後)が返ります。