APIユーザートークン認証ガイド

FrontPage

APIユーザートークン認証ガイド(暫定ドキュメント)

• (※var)の項目は、設定による可変
  

ユーザートークン認証†

IMD食品栄養データAPIの使用に際し、アクセス元IPアドレスによる認証を使用できない場合、アクセストークンによる認証を実装する必要がある。（スマホアプリ等から直接APIにアクセスを行う場合等）
API使用者は適切に、ユーザーアカウントを管理し、アプリ等使用者にトークンを配布し、またAPIサーバーからのトークン問合せに応答する必要がある。

図(暫定)

+-------------+                          +-------------+ 
|トークン管理 |<---- トークン問合せ ---- | APIサーバー |
|    サーバー |----- トークン応答   ---> |             |
+-------------+                          +-------------+
 |                                                A |
 |                                                | |
 |                  +------------+                | |
 +---- トークン --> |クライアント| ---- トークン -+ |
                    |            | <--- 食品データ -+
                    +------------+

API使用者によるトークンの管理†

API使用者は、ユーザー毎に、APIにアクセスするために必要なトークンを振り出し、管理しなければならない。

クライアントへのトークン配布†

トークンは、外部に漏洩しない適切な方法で、トークンをクライアントに配布しなければならない。

トークン問合せサーバーの実装†

API使用者は、APIサーバーからトークンの使用可否についての問合せを受け付け、適切に応答しなければならない。

クライアントのトークン送出†

スマホアプリ等、APIにアクセスを行うクライアントは、APIへりアクセス時に Authorization ヘッダーを用いてトークンを送出しなければならない。

仕様†

トークンの仕様†

トークンは以下の仕様を遵守すること。

• 半角英数及び記号-(マイナス)_(アンダースコア).(ピリオド)で構成される文字列であること
• 文字列の長さは、64文字以上4096文字以下であること
• 文字種が6以上であること

トークンの送出†

クライアントは全てのアクセスに際して、HTTPリクエストヘッダーに以下の通りアクセストークンを送出する。

Authorization: Bearer (アクセストークン)

Authorizationヘッダーは、typeをBearerとし、credentialsにアクセストークン文字列を指定する。 アクセストークンによる認証が成功した場合、APIサーバーはHTTPレスポンスコード200を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated が含まれ、値は true となる。
アクセストークンによる認証に失敗した場合、APIサーバーはHTTPレスポンスコード401を返却する。レスポンスヘッダーに X-MobadaiApi-Authenticated は含まれない。

トークン問合せサーバーの仕様†

APIサーバーへのアクセスにおいて送出されたトークンが新規トークンであった場合、API使用者の用意するトークン問合せサーバーに対してトークンの使用可否を問い合わせる。
トークン問合せサーバーは、HTTPを用いる。サーバーはTLS1.2以上を採用したhttpsでなければならない。
トークン問合せはGETメソッドを使用する。問合せ先のURLは、API使用者により任意に設定される（※各提供先向けのページ https://nmmq.mobidy.jp/utils/economyapi/ でAPI使用者が任意に設定）。

トークン問合せクエリー†

問い合わせ先URLに対して以下のクエリーを付加してアクセスを実行する。 認証ハッシュは、連携設定で「トークン検証時認証ハッシュ送出」がオンの時、sha1( アクセストークン+認証キー ) の値をセットする。

クエリ例
https://auth.yourdomain.jp/verify?access_token=dwsQJUuB86uxgTeacx5DsL8VZkQbHuCuhuoUhPbMLHZMJtK9Ey95fp55YTFWWP
uacn8DBme2s3blpF1X8GN6P6gi0xZlqaUVHxPGJhZUqLUknUQUJawzwzAn&authid=yourid&authkey=8a0e890c4d45a0d91da72c3b0e8e0189adc9e081

トークン有効時のレスポンス†

• レスポンスコード レスポンスコード200を返す。

• レスポンスボディ トークンの残り有効期間(秒)を表す expires_in を含むJSONを返す。
  例:

  { "expires_in":86400 }

トークンが有効である場合、有効期間は最大24時間(※var)とし、これ以上の値が設定された場合は、24時間に設定される。
トークンが有効期間を過ぎた場合、APIサーバーに於いて使用を拒否され、また当該トークンは以後24時間(※var)再使用が拒否される。

トークン無効時のレスポンス†

• レスポンスコード レスポンスコード400を返す。

• レスポンスボディ 規定なし

トークンが無効である場合、レスポンスが行われた後24時間(※var)、当該のトークンはAPIサーバーに於いて使用を拒否される。

トークン問合せのレート制限†

トークン問合せは、1時間あたり10000回(※var)までに制限される。制限を超えた場合、トークン問合せは行われず使用は拒否される。

APIアクセスのレート制限†

トークンを使用したAPIへのアクセスは、1時間あたり500回(※var)までに制限され、かつ、短時間に多数のクエリーを受け付けないように抑制される。レート制限が発動した時は、当該のトークンはAPIサーバーに於いて使用を拒否される。

目次

• トップページ
• APIを使用する
• 各APIの詳細
• サンプルソース