API 認証

CWS APIでは、アクセストークン方式による認証を採用しています。アクセストークンの発行方法は以下の2種類です。

• CWS認証（新方式）
• mimi認証（従来方式）

認証方式の選択について

CWS認証はCWS独自の認証基盤で認証を行います。THINKLET管理コンソール (仮称) でアプリケーションを作成し、専用のID・シークレットを用いてアクセストークンを発行します。
新規開発にはCWS認証の利用を推奨します。

mimi認証は従来のとおりmimi¹と同じ認証基盤を利用します。
mimiサービスの認証にも利用できます。

どちらの認証方式でも、取得したアクセストークンをAPIリクエストのAuthorizationヘッダにBearerトークンとして渡して利用します。詳細はAPIリファレンスをご参照ください。

CWS認証

CWS APIの認証・認可にはTHINKLET管理コンソール (仮称)で作成したアプリケーションを利用します。

CWS認証でのアクセストークンの発行

アクセストークンを発行するためには、以下の手順でアプリケーションIDとシークレットを取得してください。

1. THINKLET管理コンソール (仮称) でアプリケーションを作成します。
2. アプリケーション詳細画面でシークレットを発行してください。シークレットは一度しか表示されませんので、必ず安全な場所に控えてください。

アプリケーションIDとシークレットを利用して、アクセストークンを発行できます。

以下は、cws:application:writeとcws:application:readのスコープを指定してアクセストークンを発行する例です。
認証にはBasic認証を利用します。user-idとしてアプリケーションIDを、passwordとしてアプリケーションシークレットを指定してください。 (例えばcurlコマンドの場合は--userオプションに{アプリケーションID}:{アプリケーションシークレット}を指定すると、Basic認証が利用できます。) スコープはスペース区切りで複数指定できます。

curl -sSv https://api.console.thinklet.fd.ai/api/v1/authenticate \
  --user '{アプリケーションID}:{アプリケーションシークレット}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data 'scope=cws:application:write cws:application:read' \
  | jq

発行したアクセストークンは以下のような形のJSONオブジェクトの、access_tokenフィールドに含まれます。(...は省略した部分で、ダブルクォートで囲まれている部分がアクセストークンです。Authorizationヘッダーには省略せず渡す必要があります。)

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "bearer"
}

CWS APIを呼び出す際の、アクセストークンのリクエストヘッダへの付与例は以下です。(...部分は省略せずに渡してください。)

curl -sSv -X GET https://apis.thinklet.fd.ai/path_to_api \
  --header "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." | jq .

CWS認証のスコープ

CWS APIでは、それぞれのAPIの呼び出しに必要なスコープを定義しています。
各APIで必要なスコープが異なりますので、使用するAPIに合わせてスコープを指定ください。詳細はAPIリファレンスをご確認ください。

スコープを指定してアクセストークンを発行すると、指定されたスコープのみ利用できるアクセストークンが発行されます。

• CWS APIで利用するスコープの一覧

  スコープURI	スコープの概要
  cws:application:write	アプリケーションレベルの書き込み権限
  cws:application:read	アプリケーションレベルの参照権限
  cws:device:write	デバイスの書き込み権限
  cws:device:read	デバイスの参照権限
  cws:communication-service	遠隔支援（WebRTC）利用権限

mimi認証

CWS APIの認証・認可には音声クラウドAPIサービスmimiと同じものを利用できます。

mimi認証でのアクセストークン発行

mimiの認証基盤へアクセストークンを発行するためのAPIを呼び出し、そのアクセストークンをCWS APIのリクエストヘッダに付与してリクエストを行ってください。

CWS APIで利用するためのmimiのIDはapplicationを使用してください。トークン取得についても同様です。

mimiの認証・認可についての説明、具体的なアクセストークン発行手順については以下をご確認ください。

• https://mimi.readme.io/docs/about-auth
• https://mimi.readme.io/docs/firststep-auth

CWS APIを呼び出す際の、アクセストークンのリクエストヘッダへの付与例は以下です。

curl -sSv -X GET https://apis.thinklet.fd.ai/path_to_api \
-H "Authorization: Bearer {mimiのAPIを呼び出して取得したアクセストークン}" | jq .

mimi認証のスコープ

CWS APIでは、それぞれのAPIの呼び出しに必要なスコープを定義しています。
各APIで必要なスコープが異なりますので、使用するAPIに合わせてスコープを指定ください。詳細はAPIリファレンスをご確認ください。

スコープを指定してアクセストークンを発行すると、指定されたスコープのみ利用できるアクセストークンが発行されます。

CWS APIを利用するために必要なスコープについては以下をご確認ください。
なお、mimi認証においてCWS APIのスコープについてはお申し込みがないとご利用いただけません。

詳しくはCWS API利用申し込みをご確認ください。

• CWS APIで利用するスコープの一覧

  スコープURI	スコープの概要
  https://apis.mimi.fd.ai/auth/thinklet/applications.w	アプリケーションレベルの書き込み権限
  https://apis.mimi.fd.ai/auth/thinklet/applications.r	アプリケーションレベルの参照権限
  https://apis.mimi.fd.ai/auth/thinklet/devices.w	デバイスの書き込み権限
  https://apis.mimi.fd.ai/auth/thinklet/devices.r	デバイスの参照権限
  https://apis.mimi.fd.ai/auth/thinklet/communication-service	遠隔支援（WebRTC）利用権限

APIリファレンス

APIリファレンスはこちらをご確認ください。

Footnotes

1. mimiはFairy Devicesの提供する音声クラウドAPIサービスです。 ↩