本仕様書には、2020年に向けた社会全体のICT化推進に関する懇談会と、総務省 都市サービス高度化の実現に向けた共通クラウド基盤構築に関する実証に係る調査請負における成果物を含みます。

目次

• 更新履歴
• 概要
• 提供するAPIのドメイン
• 提供API一覧
• 認証フロー
• 各APIの詳細
• モデル一覧
• コード一覧

更新履歴

概要

おもてなしクラウド (OPaaS.io) は、利用者が登録したパーソナルデータを、利用者自身がどの情報をどのサービスへ提供するかをきめ細かくコントロールすることができるサービスである。 本ドキュメントでは、その機能を利用するためのAPIを説明している。なお公開しているAPIは、利便性向上等の観点から今後変更する可能性がある。

ここでは、APIの概略と、本ドキュメントで利用している用語を紹介する。

• APIの概略

  本APIは、パーソナルデータの読み取り、登録、削除や、パーソナルデータ提供先の管理、およびユーザー認証に関連する機能をコントロールするためのAPIを提供する。 また、OpenID Connect 1.0 によって認証を行うためのAPIが用意されており、この認証で得られたトークンを利用してAPIにアクセスする。

• 利用している用語
  • パーソナルデータ

    特定の個人を識別することができる情報である個人情報に加え、 単独では個人を識別しないが個人に関連する情報（例えば年代、趣味、嗜好等）を含めた情報を指す。 OPaaS.io はこのパーソナルデータを適切に扱うことを実現する。

  • サービス

    おもてなしクラウド内のパーソナルデータに、個人の許諾に基づいてアクセス・利用するソフトウェア。

  • サービスグループ

    サービスグループは、複数のサービスを集めてグループ化したものであり、利用者はこのグループに対してパーソナルデータ提供の許可・拒否を設定できる。

  • サービスドメイン

    サービスドメインは、サービスを提供している特定の企業や団体などを表した概念であり、このサービスドメインに対しても、利用者はパーソナルデータの提供の許可・拒否を設定できる。

  • ログインとサインイン

    APIによって表示されるHTMLの画面や、APIによってユーザに送られるメール内では、ユーザー認証を実施することを表す「ログイン」は「サインイン」と表記しているが、本仕様では「ログイン」と表記する。

  • ルール

    おもてなしクラウド内のパーソナルデータにアクセスする際に、おもてなしクラウド内部で扱われている形式と異なる形式に変換して取得するためのスクリプトを含む記述。 例えば、おもてなしクラウドで国コードはISO 3166-1 alpha-3 （日本はJPN） というように扱っているが、これをISO 3166-1 alpha-2 （日本はJP）というように表記や値を変換することなどを想定する。

提供するAPIのドメイン

APIのドメインについて

提供するAPIは下記の2つのドメインで提供される。

提供API一覧

一般のアプリ開発者向け

APIの先頭の https:// は省略する

一部の開発者向け

APIのドメインはすべて api.opaas.io なので先頭の https://api.opaas.io は省略する。

認証フロー

1. ユーザー名・パスワードを利用し、OPaaS.ioの提供する画面を利用する場合

以下のフローを参考にしてください。

auth_type に IDPW（パスワード認証）を指定した場合の認証の流れは以下の通りである。ただし、リクエストパラメータに正しい（エラーとならない）データを指定して実行したものとする。

本APIの処理が成功した場合は、下記の手順 7 で 認可code を発行するが、どのような流れ（途中でユーザ登録や、パスワードのリセットの処理が間に挟まった場合なども含む）で 7 に至った場合でも、本APIを最初に実行した際に与えたリクエストパラメータに対応する 認可code が発行される（手順6が実行された場合は、そこでユーザが許諾したパーソナルデータのみ許諾する）。

1. API実行時にユーザがログインしていない場合は2へ。ログインしている場合は 5 へ。
2. ログイン画面が表示される。
   • 正しいID、パスワードを入力した場合 5 へ。
   • Sign Up ボタンをクリックした場合は 3 へ。
   • Reset password ボタンをクリックした場合は 4 へ。
3. アカウント登録手続きの流れ
   1. アカウント登録画面が表示される。メールアドレスを入力すると、そのメールアドレスにメールが送られ、メールが送られたことを表す画面が表示される。
      アカウント登録画面は後述の GET accounts.opaas.io/signup によって直接表示することができる。
   2. 受信したメール内のリンクをクリックすることで、パスワード設定画面が表示される。
   3. パスワードを設定するとアカウントの登録完了画面が表示され、その中のログインボタンをクリックすると 2 へ戻り、ログイン画面が表示される。また、ユーザにはアカウント登録完了のメールが送られる。
4. パスワード変更手続きの流れ
   1. パスワードリセット画面が表示される。メールアドレスを入力すると、そのメールアドレスにメールが送られ、メールが送られたことを表す画面が表示される。
      パスワードリセット画面は後述の GET accounts.opaas.io/resetpassword によって直接表示することができる。
   2. 受信したメール内のリンクをクリックすることで、パスワード変更画面が表示される。
   3. パスワードを設定するとパスワードの変更完了画面が表示され、その中のログインボタンをクリックすると 2 へ戻り、ログイン画面が表示される。また、ユーザにはパスワード変更完了のメールが送られる
5. ユーザがサービスに対して許諾していないパーソナルデータがある場合は 6 へ。なければ 7 へ。
6. パーソナルデータ許諾画面が表示される。許諾するパーソナルデータを選択すると 7 へ。
7. リクエストパラメータ redirect_uri で指定したアドレスに、URIクエリとしてユーザが許諾したパーソナルデータが入ったアクセストークンを発行するための 認可code を加えたアドレスにリダイレクトされる。

2. ICカードを利用して認証する場合

手順1.

サイネージ利用などのブラウザを利用しない場合には、直接おもてなしクラウドの認証要求受付APIを呼び出してください。認証要求受付API(GET accounts.opaas.io/oauth2/authorize)は以下のパラメータを設定してアクセスします。

auth_type：IDM
authori_screen：OFF
※ICカード認証を実施かつ許諾画面は表示しないとした場合です。

• ICカードによる認証がエラーとなった場合、HTTPステータスコード200を返却し、レスポンス内にエラーに関する情報が入ります。内容は、ICカード認証受付APIの仕様をご参照ください。

手順2:

HTTPステータスコードで302でLocationヘッダに認可コード付きの認証後遷移先URLが設定されます。

• 認証後遷移先URLは認証要求受付APIに要求した際のredirect_uriです。
• 認証フロー中にエラーが発生した場合、 Locationヘッダにエラーコード(error)付きの認証後遷移先URLが設定されます。認可コードは付きません。
• 応答例は以下の通りです。

---------------------------------------------
HTTP/1.1 302 Found
Location: https://serviceA.co.jp/home.jsp?state=statevalue&code=WZHm7cukADLdhkmz
★★ Locationの「https://serviceA.co.jp/home.jsp」部分がredirect_uriです。★★
★★ redirect_uriのクエリ「code」に設定された値が認可コードです。★★
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 0
Keep-Alive: timeout=5, max=99
Connection: Keep-Alive
---------------------------------------------

手順3:

手順2で発行された認可コード利用してトークン要求受付APIへアクセストークンの取得要求を行い、取得したアクセストークンを用いて、パーソナルデータ取得APIへのアクセスを行って下さい。

3. QRコードを利用して認証する場合

（利用者側）手順1.

あらかじめ、GET accounts.opaas.io/oauth2/authorize、POST accounts.opaas.io/oauth2/token を実行して、ユーザの認証済のアクセストークンを発行しておいてください。QRコードを利用した認証では、このアクセストークンを使って、一度だけ有効なユーザを認証するQRコードを発行します。

（利用者側）手順2.

手順1で得たアクセストークンを使って、GET api.opaas.io/api/v1/users/auth/qr を実行して下さい。ユーザの認証用トークンが入ったQRコードが生成されます。

下記の例ではQRコードの画像が入ったファイルが生成されます。

https://api.opaas.io/api/v1/users/auth/qr?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

（サービス側）手順3:

QRコード内には、qrtoken=xxxxxxxxx&state=yyyyyyyy のようなデータが格納されているので、これらと auth_type=QR をリクエストパラメータとし、他のリクエストパラメータを設定して GET accounts.opaas.io/auth/authorize を実行して下さい。

QRコードを利用した認証では、パーソナルデータの許諾画面は表示されません（aurhori_screenの設定は必ずOFFとみなされる）。リクエストパラメータ scope に設定されたパーソナルデータのうちユーザがパーソナルデータ許可ポリシーで"許諾"の設定を行っているもののみ提供します。

QRコード内のユーザを認証するトークンは一度使うか、発行後15分経過すると失効します。失効したトークンをリクエストパラメータとして GET accounts.opaas.io/auth/authorize を実行するとエラーとなります。

• QRコード認証がエラーとなった場合、HTTPステータスコード302を返却し、レスポンス内にエラーに関する情報が入ります。内容は、GET accounts.opaas.io/auth/authorize の仕様をご参照ください。

（サービス側）手順4:

HTTPステータスコードで302でLocationヘッダに認可コード付きの認証後遷移先URLが設定されます。

• 認証後遷移先URLは認証要求受付APIに要求した際のredirect_uriです。
• 認証フロー中にエラーが発生した場合、 Locationヘッダにエラーコード(error)付きの認証後遷移先URLが設定されます。認可コードは付きません。
• 応答電文例は以下の通りです。

---------------------------------------------
HTTP/1.1 302 Found
Location: https://serviceA.co.jp/home.jsp?state=statevalue&code=WZHm7cukADLdhkmz
★★ Locationの「https://serviceA.co.jp/home.jsp」部分がredirect_uriです。★★
★★ redirect_uriのクエリ「code」に設定された値が認可コードです。★★
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Content-Length: 0
Keep-Alive: timeout=5, max=99
Connection: Keep-Alive
---------------------------------------------

（サービス側）手順5:

手順4で発行された認可コード利用してトークン要求受付APIへアクセストークンの取得要求を行い、取得したアクセストークンを用いて、パーソナルデータ取得APIへのアクセスを行って下さい。

各APIの詳細

認証要求受付API (GET accounts.opaas.io/oauth2/authorize )

認証要求の受付を行い、その後http仕様に則った認証フロー後に認証応答を返却する。認証プロトコルはOpenID Connectを利用。

認証要求の受付の結果、ユーザのログインが必要になった場合はログイン画面のHTMLを返し、そのページからのログインが成功した場合に認証受付を続行する。

認証要求の受付の結果、ユーザからの許諾が必要なパーソナルデータが存在する場合は、許諾画面のHTMLを返し、scopeのうち、そのページでユーザが許諾したパーソナルデータのみを許諾する認可codeを提供する。本APIはユーザからの許諾が必要であるかどうかを下記の手順で確認する。

1. ユーザのサービスへのパーソナルデータ提供ポリシーのうち、要求を行ったサービスに対するポリシーを収集する（パーソナルデータ提供ポリシーは後述の GET or PUT or PATCH api.opaas.io/api/v1/users/permissions によって直接取得、または変更することができる）。
2. 収集したポリシーのうち、要求されている各パーソナルデータに関するポリシーをそれぞれ取得する。
3. 要求されているパーソナルデータに対するポリシーが一つも設定されていない場合は、そのパーソナルデータは許諾されていないものとみなす。
4. 要求されているパーソナルデータに対するポリシーが一つだけ設定されている場合はそのポリシーに設定されているアクセス権限の種類によって許諾されているかどうかを判断する。ポリシーが複数設定されている場合は、ポリシーの type に対して service > service_domain > service_group > reliability の順で優先度をつけ、最も優先度の高いポリシーのアクセス権限の種類によって許諾されているかどうかを判断する。

本APIは、許諾画面でユーザが「If this check box is enabled, the server will save your consent, so that you won't be prompted for the same authorization multiple times.」と表示されたチェックボックスをONにして許諾を行うと、要求されているすべてのパーソナルデータに対して、ユーザが許諾画面で設定した内容に応じたパーソナルデータ提供ポリシーを type=service で自動的に保存する。チェックボックスをOFFにして許諾を行うと、パーソナルデータ提供ポリシーは編集されない。

リクエストパラメータ

注意事項

QRコード認証について

QRコード認証を行う場合、後述の GET api.opaas.io/api/v1/users/auth/qr によって得られるQRコード内に記載されたユーザのトークンを用いてユーザの認証を行う。 具体的な手順は以下の通り。

1. 本APIでユーザの認証要求の受付を行い、得られた認可コードを用いて POST accounts.opaas.io/oauth/token を実行してアクセストークンを取得する。
2. 1.で取得したアクセストークンを用いて後述の GET api.opaas.io/api/v1/users/auth/qr を 実行し、1.で認証したユーザの認証トークンが記載されたQRコードを得る。
3. 本APIに対してリクエストパラメータとして、auth_type=QR、qrtoken=「2.で取得したユーザの認証トークン」を設定して実行する。これら以外のリクエストパラメータは、他の認証方式と同様のものを指定する。

QRコード認証を行った場合、ユーザの認証トークンによってユーザが認証されるため、ログイン画面は表示されない。

また、authori_screen はその設定値に関わらず、OFF として実行されるため、許諾画面が表示されることはない。

qrtoken（ユーザの認証トークン）について

GET api.opaas.io/api/v1/auth が生成する QRコード内に記載された qrtoken の寿命は 15 分であり、生成後15分経過すると失効する。

qrtokenは一度使用すると失効する。

失効した qrtoken を本APIのリクエストパラメータに指定して実行するとエラーとなる。

response_type について

2018年10月5日 時点では code のみ対応している。 今後、他の方式も対応予定。

パーソナルデータの提供許諾ポリシー取得・設定APIについて

後述の GET,PUT or PATCH api.opaas.io/api/v1/users/permissions を参照。

レスポンスパラメータ

ログイン、または許諾が必要な場合は、ステータスコード200で、HTMLが返る。

認証要求が成功した場合は、UA経由のリダイレクトで応答を返却する。

HTTPステータスコード

エラーレスポンスパラメータ

error の詳細説明

サンプル

リクエストサンプル

パスワード認証の場合

・GET
https://accounts.opaas.io/oauth2/authorize?scope=openid+email+passport_name&response_type=code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=https%3A%2F%2Ftest-rp.co.jp%2F&state=statevalue&nonce=noceXXXXXX&authori_screen=OFF

IDM認証の場合

・GET
https://accounts.opaas.io/oauth2/authorize?scope=openid+email+passport_name&response_type=code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=https%3A%2F%2Ftest-rp.co.jp%2F&state=statevalue&nonce=noceXXXXXX&auth_type=IDM&IDM=xxxxxxxx&authori_screen=OFF

QRコード認証の場合

・GET
https://accounts.opaas.io/oauth2/authorize?scope=openid+email+passport_name&response_type=code&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=https%3A%2F%2Ftest-rp.co.jp%2F&state=statevalue&nonce=noceXXXXXX&auth_type=QR&qrtoken=xxxxxxxx

補足

リクエストサンプルで、GET メソッドを使用する場合で、リクエストヘッダに記述する必要のあるデータがない場合は、上記のように、「・GET」の次の行にURLのみを表記する。

レスポンスサンプル

正常時

HTTPステータスコード

302

レスポンス内容

HTTP/1.1 302 Found
Location: https://test-rp.co.jp?state=statevalue&code=NsjJpaNnH4u9BOnh

異常時(リダイレクト応答)

HTTPステータスコード

302

レスポンス内容

HTTP/1.1 302 Found
Location: https://test-rp.co.jp?error=invalid_request&error_description=Unsupported%20response_type%20value&state=statevalue

異常時(400応答)

HTTPステータスコード

400

レスポンス内容（client_id が不正な場合）

{
  "status": "Client ID Error",
  "message": "The client identifier (client_id) is missing or invalid."
}

レスポンス内容（auth_type が 'QR' の場合で、qrtokenが不正、または失効した場合）

{
  "status": "invalid_token",
  "message": "The request parameter qrcode is expired or invalid."
}

ユーザ登録要求受付API (GET accounts.opaas.io/oauth2/signup )

ユーザ登録認証要求の受付を行うWebページを表示する。

本APIは、以下の3種類の方法で実行される。

1. 前述の、GET accounts.opaas.io/oauth2/authorize 実行時に、ログインが行われていなかった場合に表示されるログイン画面で sign up ボタンをクリックした際に実行される。詳細は GET accounts.opaas.io/oauth2/authorize の説明内の流れ（以下「authorizeの処理の流れ」と表記）を参照。
2. 本APIを直接実行することで、aurhorize の処理の流れの 手順1,2 を飛ばして、直接 手順3 のユーザ登録画面へ移行することができる。
3. 本APIを リクエストパラメータ client_id を設定せずに直接実行することで、authorize の処理の流れとは関係なく、ユーザ登録の処理のみを行う事ができる。1,2 と異なり、ユーザ登録完了時に、ログインのボタンが表示されることはない。

リクエストパラメータ

本APIは上記の 1,2 の方法で実行された場合は、 GET accounts.opaas.io/oauth2/authorizeの処理の流れに組み込まれた API であるため、リクエストパラメータは GET accounts.opaas.io/oauth2/authorize と同じである。従って、リクエストパラメータの一覧は省略する。

上記の 3 の方法で実行された場合は、本APIはリクエストパラメータを必要としない。

レスポンスパラメータ

不正なリクエストや、パラメータがない場合は、ログインID（メールアドレス）を登録するためのHTMLがステータスコード200で返る。それ以外の場合はすべてエラーである。

HTTPステータスコード

エラーレスポンスパラメータ

GET accounts.opaas.io/oauth2/authorize と同じ

サンプル

正常時に HTML が返る以外は、GET accounts.opaas.io/oauth2/authorize とほぼ同一なので省略

ユーザのパスワード変更要求受付API (GET accounts.opaas.io/oauth2/resetpassword )

ユーザのパスワード変更要求の受付を行うWebページを表示する。

本APIは、以下の3種類の方法で実行される。

1. 前述の、GET accounts.opaas.io/oauth2/authorize 実行時に、ログインが行われていなかった場合に表示されるログイン画面で reset password ボタンをクリックした際に実行される。詳細は GET accounts.opaas.io/oauth2/authorize の説明内の流れ（以下「authorizeの処理の流れ」と表記）を参照。
2. 本APIを直接実行することで、aurhorizeの処理の流れの 手順1,2 を飛ばして、直接 手順4 のパスワード変更画面へ移行することができる。
3. 本APIを リクエストパラメータ client_id を設定せずに直接実行することで、authorize の処理の流れとは関係なく、パスワードの変更の処理のみを行う事ができる。1,2 と異なり、パスワード変更完了時に、ログインのボタンが表示されることはない。

本APIは、パスワード変更完了時に、それまでログイン状態であったとしても、強制的にログアウトする。

リクエストパラメータ

本APIは上記の 1,2 の方法で実行された場合は、 GET accounts.opaas.io/oauth2/authorizeの処理の流れに組み込まれた API であるため、リクエストパラメータは GET accounts.opaas.io/oauth2/authorize と同じである。従って、リクエストパラメータの一覧は省略する。

上記の 3 の方法で実行された場合は、本APIはリクエストパラメータを必要としない。

レスポンスパラメータ

不正なリクエストパラメータがない場合は、パスワードを変更するユーザID（メールアドレス）を入力するためのHTMLがステータスコード200で返る。それ以外の場合はすべてエラーである。

HTTPステータスコード

エラーレスポンスパラメータ

GET accounts.opaas.io/oauth2/authorize と同じ

サンプル

正常時に HTML が返る以外は、GET accounts.opaas.io/oauth2/authorize とほぼ同一なので省略

ログアウト要求受付API (GET accounts.opaas.io/oauth2/logout )

ユーザのログアウト要求の受付を行う。

リクエストパラメータとして、client_id と redirect_uri を受け取り、redirect_uri がclient_id のクライアントに登録されていた場合のみ、ユーザのログアウト処理を行い、redirect_uri にリダイレクトする。

ユーザがログインしていなかった場合は、エラーとはせず、redirect_uriにリダイレクトする。

リクエストパラメータ

レスポンスパラメータ

ログアウトが成功した場合は、UA経由のリダイレクトで応答を返却する。本APIはリダイレクト時に特別なレスポンスパラメータを付与しない。

HTTPステータスコード

サンプル

リクエストサンプル

・GET
https://accounts.opaas.io/oauth2/logout?client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&redirect_uri=https%3A%2F%2Ftest-rp.co.jp

レスポンスサンプル

正常時

HTTPステータスコード

302

レスポンス内容

HTTP/1.1 302 Found
Location: https://test-rp.co.jp

異常時(パラメータエラー時）

HTTPステータスコード

400

レスポンス内容

client_id が不正な場合

{
  "status": "Parameter error",
  "message": "Parameter client_id is required or invalid."
}

redirect_uri が不正な場合

{
  "status": "Parameter error",
  "message": "Parameter redirect_uri is required or invalid."
}

トークン要求受付API (POST accounts.opaas.io/api/v1/oauth2/token )

認証要求受付の結果をトークンとして発行する。

リクエストパラメータ

下記で、必須/任意の所に(A)と記述されているものは、grant_typeに"authorization_code"を指定した場合、(R)と記述されているものは、grant_typeに"refresh_token"を指定した場合を表す。

初回の認証時には grant_type に authorization_code でトークン（1時間有効）を取得し、その後は grant_type に refresh_token を指定し、リフレッシュトークン（24時間有効）を利用してトークンを再発行することができる。トークンの有効期限が切れた場合には再度認証（GET accounts.opaas.io/oauth2/authorize）が必要となる。

レスポンスパラメータ

HTTPステータスコード

エラーレスポンスパラメータ

サンプル

リクエストサンプル

POST  /oauth2/token HTTP/1.1
Host: accounts.opaas.io

grant_type=authorization_code&code=NsjJpaNnH4u9BOnh&redirect_uri=https%3A%2F%2Ftest-rp.co.jp%2F&client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&client_secret=ZJYCqe3GGRvdrudKyZS0XhGv_Z45DuKhCUk0gBR1vZk

codeのauth_typeがIDM の場合

POST /oauth2/token HTTP/1.1
Host: accounts.opaas.io
HTTP-X-AUTHORIZATION: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

client_id=xxxxxxx&client_secret=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&grant_type=authorization_code&redirect_uri=https%3A%2F%2Ftest-rp.co.jp%2F&code=NsjJpaNnH4u9BOnh

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzA5NzUwMTEsImF6cCI6IkNMSUFOVDk5OTkiLCJzdWIiOiIwMDAwMSIsIm5vbmNlIjoibm9jZVhYWFhYWCIsImF1ZCI6IkNMSUFOVDk5OTkiLCJpc3MiOiJodHRwczpcL1wvMTkyLjE2OC4yMC43OFwvIiwiaWF0IjoxNDcwOTcxNDExfQ.oN4YB5U6m-L-m9bHS1cXVW0DkEAPLtajA0mCGdEs0VU"
}

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status":"error",
  "error_description": "invalid_request"
}

ユーザーの認証用QRコード取得API ( GET api.opaas.io/api/v1/users/auth/qr )

ユーザーの認証用QRコードを取得するAPIである。

認証ヘッダに付与されたアクセストークンに基づき、ユーザIDを割り出し、そのユーザに対する認証トークンを生成する。生成した認証トークンは、GET accounts.opaas.io/oauth2/authorize において、（auth_type=QRを指定して）QRコード認証を行う際に、リクエストパラメータ qrtoken に指定して使用する。

QRコードを用いた認証の手順の詳細については GET accounts.opaas.io/oauth2/authorize の「QRコード認証について」を参照のこと。

本APIは、生成した認証トークンの情報を含んだQRコードの画像を出力する。

本APIで生成した認証トークンの寿命は 15 分であり、生成後15分経過すると失効する。また、認証トークンは一度使用すると失効する。

失効した認証トークンを GET accounts.opaas.io/oauth2/authorize のリクエストパラメータとして使用するとエラーとなる。

リクエストパラメータ

レスポンスパラメータ

HTML内の画像または、ファイルとしてQRコードが出力される。

QRコード内のデータには以下の内容が記載される。

qrtoken=「ユーザの認証トークン」&state=「リクエストパラメータ state に設定された値」

HTTPステータスコード

サンプル

リクエストサンプル

リスポンスを画像ファイルで取得する場合。

・GET
https://api.opaas.io/api/v1/users/auth/qr?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

リスポンスをHTML内の画像で取得する場合

・GET
https://api.opaas.io/api/v1/users/auth/qr?html&access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

HTMLまたはpng形式の画像。

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（アクセストークン内のscopeにopenidが含まれていない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token"
}

異常時（おもてなし内部エラーの場合）

HTTPステータスコード

500

レスポンス内容

技術的な問題が発生しました。ご迷惑をおかけしております。

パーソナルデータ取得API（GET api.opaas.io/api/v1/user_attributes）

おもてなしクラウドの提供するパーソナルデータ取得APIである。 ユーザーがおもてなしクラウドへ登録し、サービスへの提供を許可しているパーソナルデータのみを取得可能である。

OpenID Connect 1.0のUserInfoEndpointの仕様に準拠する。 認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。 存在しないパーソナルデータを指定された場合は、無視する。

リクエストパラメータ

必須(*)は、それが記載されているうちの、いずれか一つを必ず指定する必要があることを表す。

注意事項

パーソナルデータ passport_image について

本APIで取得したパーソナルデータ passport_image のURLの有効期限は10分である。取得後10分以上経過した場合は、そのURLから画像にアクセスすることはできなくなるため、必要な場合は再度 GET user_attributes で passport_image のURLを取得する必要がある。

ruleについて

2018年10月5日 時点では rule機能は未提供。 今後対応予定。

レスポンスパラメータ

レスポンスボディへの返却は、暗号化を実施しない場合は"application/json"形式、暗号化を実施する場合は"application/jwt"形式にて返却される。

”appliaction/json”形式の場合、応答レスポンスボディ内にはJSONプレーンテキスト形式のクレームセットデータのみが返却される。 ”application/jwt”形式の場合、応答レスポンスボディ内にはJWT(Json Web Token)形式のデータのみが返却される。JWT形式はBASE64URLエンコードされる。 JSONプレーンテキストまたはJWTクレームセットより下記応答形式のパラメータ(sub,iss,aud)を取得することができる。

注意事項

application/jwt形式 について

2018年10月5日 時点では application/json形式のみ対応している。 今後、application/jwt形式も対応予定。

HTTPステータスコード

注意事項

ステータスコード500の場合のみ、jsonではなく、HTMLでレスポンス内容が返る（他のすべてのAPIについても同様）。

サンプル

リクエストサンプル

アクセストークンをヘッダで指定する場合

GET /api/v1/user_attributes?rule=ecDMLZ2F9H4KotFoeI5TTgO1tM9SG1f1,KdMr2Bd1sTniWgf0XOecwRqLhRYxot7w&filter=first_name,family_name,email,gender HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

アクセストークンをクエリで指定する場合

・GET
https://api.opaas.io/api/v1/user_attributes?rule=ecDMLZ2F9H4KotFoeI5TTgO1tM9SG1f1,KdMr2Bd1sTniWgf0XOecwRqLhRYxot7w&filter=first_name,family_name,email,gender&access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容（要求したパーソナルデータ項目がすべて提供できる場合）

・暗号化しない場合

{
  "sub":"https://accounts.opaas.io/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "familiy_name":"Taro",
  "first_name":"Suzuki",
  "gender":"1",
  "email":"example@service.opaas.io",
  "aud":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "iss":"https://api.opaas.io/"
}

・パーソナルデータを暗号化する場合 ※パーソナルデータの暗号化は今後リリース予定

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

レスポンス内容（要求したパーソナルデータの一部のみユーザーが提供を許諾している場合）

・パーソナルデータを暗号化しない場合

{
  "sub":"https://accounts.opaas.io/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "family_name":"Taro",
  "email":"example@service.opaas.io",
  "aud":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "iss":"https://api.opaas.io/"
}

・パーソナルデータを暗号化する場合

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

※許可されたパーソナルデータのみ取得できる

レスポンス内容（「ルール」によってセマンティクス変換が正常に変換できた場合）

※「ルール」を利用したパーソナルデータのセマンティクス変換は今後リリース予定

・パーソナルデータを暗号化しない場合

{
  "sub":"https://accounts.opaas.io/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "year":"1982" ,
  "year_jpn":"S57",
  "aud":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "iss":"https://api.opaas.io/"
}

・パーソナルデータを暗号化する場合

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

※西暦（パーソナルデータ："year"）を和暦（パーソナルデータ："year_jpn"）へセマンティクス変換した場合の例

レスポンス内容（セマンティクス変換でエラーが発生した場合）

・パーソナルデータを暗号化しない場合

{
  "sub":"https://accounts.opaas.io/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "year":"1982" ,
  "aud":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "iss":"https://api.opaas.io/"
}

・暗号化する場合

eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

※西暦（パーソナルデータ："year"）を和暦（パーソナルデータ："year_jpn"）へセマンティクス変換できない場合の例

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（アクセストークン内のscopeにopenidが含まれていない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token"
}

異常時（おもてなし内部エラーの場合）

HTTPステータスコード

500

レスポンス内容

技術的な問題が発生しました。ご迷惑をおかけしております。

サービス一覧取得API（GET api.opaas.io/api/v1/services）

サービスの一覧を取得する。

リクエストパラメータ

必須(*)は、それが記載されているうちの、いずれか一つを必ず指定する必要があることを表す。

レスポンスパラメータ

サービス(service)の構造

HTTPステータスコード

サンプル

リクエストサンプル

アクセストークンをヘッダで指定する場合

GET /api/v1/services/ HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx

アクセストークンをクエリで指定する場合

・GET
https://api.opaas.io/api/v1/services/?access_token=xxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容（アクセストークンのユーザが、サービスドメイン 20000000000000000020000000000000 の管理者権限を持ち、20000000000000000020000000000001 の管理者権限を持たない場合）

{
    "total_num": 2,
    "start_pos": 1,
    "services": [
        {
            "service_id": "2000000000000000001000000000000a",
            "name": "service1",
            "title": "サービス１",
            "description": "説明１",
            "icon_url": "http://test.com",
            "tags": [ "abcde" ],
            "service_domain_id": "20000000000000000020000000000000",
            "service_groups": [ "20000000000000000030000000000000" ],
            "geohash": "u4pruydqqvj",
            "floor": "1.0",
            "attrs": [ "age", "destination" ],
            "reg_date": "2018-10-07"
            "canmodify_userdata": false,
            "client": "567541",
            "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "passphrase": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "redirect_uris": [ "http://example.com/" ]
        },
        {
            "service_id": "2000000000000000001000000000000b",
            "name": "service2",
            "title": "サービス２",
            "description": "説明２",
            "icon_url": "http://test.com",
            "tags": [],
            "service_domain_id": "20000000000000000020000000000001",
            "service_groups": [ "20000000000000000030000000000000" ],
            "geohash": "u4pruydqqvj",
            "floor": "10.0",
            "attrs": [ "address_line_1", "address_line_2", "country" ],
            "reg_date": "2018-10-07"
        },
    ]
}

注意事項

サービスが一つも登録されていない場合でも、エラーとはしない。

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid token",
  "message": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（アクセストークンが openid を許諾しない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "insufficient_scope",
  "message": "The request requires higher privileges than provided by the access token"
}

異常時（リクエストパラメータ has_signage に 0, 1 以外の値を設定した場合）

HTTPステータスコード

400

レスポンス内容

{
    "status": "error",
    "message": "Parameter error. Parameter has_signage must be 0 or 1. Current value is 2"
}

サービスの情報取得API（GET api.opaas.io/api/v1/services/{id}）

サービスの情報を取得する。

リクエストパラメータ

必須(*)は、それが記載されているうちの、いずれか一つを必ず指定する必要があることを表す。

レスポンスパラメータ

GET api.opaas.io/api/v1/services/ の個々のサービスのレスポンスパラメータと同じ形式で出力される。

HTTPステータスコード

サンプル

リクエストサンプル

アクセストークンをヘッダで指定する場合

GET /api/v1/services/2000000000000000001000000000000a/ HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxx

アクセストークンをクエリで指定する場合

・GET
https://api.opaas.io/api/v1/services/2000000000000000001000000000000a/?access_token=xxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
    "service_id": "2000000000000000001000000000000a",
    "name": "service1",
    "title": "サービス１",
    "description": "説明１",
    "icon_url": "http://test.com",
    "tags": [ "abcde" ],
    "service_domain_id": "20000000000000000020000000000000",
    "service_groups": [ "20000000000000000030000000000000" ],
    "geohash": "u4pruydqqvj",
    "floor": "1.0",
    "attrs": [ "age", "destination" ],
    "reg_date": "2018-10-07"
}

異常時（{id}のサービスが存在しない場合）

HTTPステータスコード

404

レスポンス内容

{
    "status": "error",
    "message": "service id xxxxxxxxxxxxxxxxxxxxxxxxx does not exist."
}

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid token",
  "message": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（アクセストークンが openid を許諾しない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "insufficient_scope",
  "message": "The request requires higher privileges than provided by the access token"
}

ルール一覧取得API（GET api.opaas.io/api/v1/rules）

ルールの情報を取得する。(今後提供予定)

OpenID Provider Metadata の取得API（GET accounts.opaas.io/.well-known/openid-configuration）

OpenID Connect Discovery (https://openid.net/specs/openid-connect-discovery-1_0.html) の OpenID Provider Metadata の情報を取得する。

リクエストパラメータ

なし

レスポンスパラメータ

OpenID Provider Metadata の情報がJSON形式で返る。

HTTPステータスコード

サンプル

リクエストサンプル

GET /.well-known/openid-configuration HTTP/1.1
Host: accounts.opaas.io

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "issuer": "https://accounts.opaas.io",
  "authorization_endpoint": "https://accounts.opaas.io/oauth2/authorize",
　以下略
}

id_token の公開鍵の情報の取得API（GET accounts.opaas.io/oauth2/jwks）

POST accounts.opaas.io/oauth2/token のレスポンスパラメータの id_token の暗号化で使われている公開鍵暗号の公開鍵の情報を取得する。

リクエストパラメータ

なし

レスポンスパラメータ

公開鍵の情報がJSON形式で返る。

HTTPステータスコード

サンプル

リクエストサンプル

GET /oauth2/jwks HTTP/1.1
Host: accounts.opaas.io

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "keys": [
    { 
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "b6a08db36ca10a325076003e90a7266d",
      "n": "qKoplSEdGtXEiI-wiuHewgbA1vhZiU6-ktVTKHB-LMLoee_1Qpv_TbELx0uXAsCH-z8swabD3kCp9snmIqYQauYediqbuCQEA3K7TVrTcmdChxhg9oRsahqbVqS5LQyhidQJ9wbf_I0kSb_ysC4SADoos0-Uordr19vG7bSwP7FZHmdHdqdb4uJvRfIPSahM3MJk87wU2rmo9u6pUSqWqQTlFtl9BXHt7T2FF3qo0FuWGHhDlRXYJSeuUav5U_2JFxbwawxhrKdY-G4JBr1KENuv7rChIYYp7Td_2lS9_0N_3mBw-euDGLG3SxWgLA0dM4XK35fElCirVvqdxni7LQ",
      "e": "AQAB"
    }
  ]
}

パーソナルデータを変更するアプリの開発者向け

パーソナルデータ更新API（PUT or PATCH api.opaas.io/api/v1/user_attributes）

おもてなしクラウドの提供するパーソナルデータ更新APIである。 ユーザーがサービスへの提供を許可しているパーソナルデータのみ、 さらにサービスがパーソナルデータの編集権限を持つ場合のみ更新可能である。

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。 存在しないパーソナルデータを指定された場合は、無視する。

本APIは、PUTとPATCHメソッドで同一の動作を行う。

パーソナルデータのうち、 passport_image は後述の PUT or PATCH api.opaas.io/api/v1/user_attributes/image で変更する。また、email については変更できない。

リクエストパラメータ

レスポンスパラメータ

更新したパーソナルデータ名と更新後の値をJSONのオブジェクト形式で返す。

HTTPステータスコード

サンプル

リクエストサンプル

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"age": 20, "destination": ["Tokyo", "Osaka"]}}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容（要求したパーソナルデータがすべて変更できる場合）

{"age": 20, "destination": ["Tokyo", "Osaka"]}

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（サービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Service xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is not allowed to change user attribute."
}

異常時（許可されていないパーソナルデータを更新しようとした場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. You are not allowed to change scope age."
}

補足

現状では許可されていないパラメータが複数あった場合でも、messageには最初に見つかったscopeだけを表示する。

リクエストサンプル（パーソナルデータを削除する場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"age": ""}}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{"age": null}

補足

データを削除した場合は、レスポンス内容の更新後の値は null となる。

リクエストサンプル（存在しないパーソナルデータ（dummy）を更新しようとした場合）

PUT /api/v1/user_attributes
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"age": 20, "dummy": 0}}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{"age": 20}

補足

存在しないパーソナルデータを変更しようとした場合は無視され、エラーとはしない。

リクエストサンプル（指定されたパラメータがJSONフォーマットでない場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":}

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter {\"user_attribute\":} is not JSON format"
}

リクエストサンプル（パラメータに user_attribute が設定されていない場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"dummy":{"age": 0}}

レスポンスサンプル

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter user_attribute is required."
}

リクエストサンプル（指定されたパーソナルデータの設定値が不正な場合)

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"gender": 5}}

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. {'gender': [\"Value '5' is not a valid choice.\"]}"}
}

補足

複数のパーソナルデータを同時に更新しようとした場合、一つでもパーソナルデータの設定値が不正であった場合は、他のパーソナルデータの更新値が適切であったとしても、パーソナルデータは一切更新されない。

リクエストサンプル（指定されたパーソナルデータのフォーマットが異なる場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"priority_language": "aaa"}}

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error", 
  "message": "Parameter error. {'priority_language': ['Value aaa must be list.']}"
}

リクエストサンプル（パーソナルデータemailを更新しようとした場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"email": ""}}

レスポンスサンプル

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
   "message": "Parameter error. Scope email can not be modified."
}

リクエストサンプル（パーソナルデータpassport_imageを更新しようとした場合）

PUT /api/v1/user_attributes HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

{"user_attribute":{"passport_image": ""}}

レスポンスサンプル

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Please use PUT or PATCH user_attributes/image to change passport_image."
}

パーソナルデータ passport_image 更新API（PUT or PATCH api.opaas.io/api/v1/user_attributes/image）

おもてなしインフラの提供するパーソナルデータ passport_image の更新を行うAPIである。 ユーザーが passport_image への提供を許可している場合のみ、 さらにサービスがパーソナルデータの編集権限を持つ場合のみ更新が可能である。

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。

本APIは、PUTとPATCHメソッドで同一の動作を行う。

リクエストパラメータ

レスポンスパラメータ

なし

HTTPステータスコード

サンプル

リクエストサンプル

PUT /api/v1/user_attributes/image HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: xxxxxxx
Content-Type: multipart/form-data; 以下省略

curlでリクエストした場合の例

curl "https://api.opaas.io/api/v1/user_attributes/image" -L -X PATCH -H "Authorization: Bearer xxxxxxxxxxxxxxx" -F upload_file=@C:\Users\xxxxx\xxxxxx.jpg

レスポンスサンプル

正常時

HTTPステータスコード

201

レスポンス内容

なし

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（サービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Service xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is not allowed to change user attribute."
}

異常時（passport_imageが許可されていない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Scope passport_image is required."
}

パーソナルデータ passport_image 削除API（DELETE api.opaas.io/api/v1/user_attributes/image）

おもてなしクラウドの提供するパーソナルデータ passport_image の削除を行うAPIである。 ユーザーが passport_image への提供を許可している場合のみ、 さらにサービスがパーソナルデータの編集権限を持つ場合のみ削除が可能である。

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。

リクエストパラメータ

レスポンスパラメータ

なし

HTTPステータスコード

サンプル

リクエストサンプル

DELETE /api/v1/user_attributes/image HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx
Content-Length: 23
Content-Type: application/x-www-form-urlencoded

item_key=passport_image

レスポンスサンプル

正常時

HTTPステータスコード

204

レスポンス内容

なし

補足

パーソナルデータに passport_image が存在しない場合もエラーとはならず、正常終了する。

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
  "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

異常時（サービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Service xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is not allowed to change user attribute."
}

異常時（Bodyにitem_keyが記述されていない場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter item_key is required."
}

異常時（Bodyのitem_keyにpassport_image以外が設定されていた場合（下記の例ではdummyを設定））

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter item_key dummy is not passport_image."
}

異常時（passport_imageが許可されていない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Scope passport_image is required."
}

パーソナルデータ要求・変更・提供履歴取得API（GET api.opaas.io/api/v1/user_attributes/history）

パーソナルデータをサービスへ要求・提供した記録およびパーソナルデータを変更した履歴を取得する。 サービスが許可されているパーソナルデータに関する記録のみ取得できる。

リクエストパラメータ

必須(*)は、それが記載されているうちの、いずれか一つを必ず指定する必要があることを表す。

レスポンスパラメータ

結果はJSONのオブジェクト形式で下記の表の内容を返す。

historyの構造

HTTPステータスコード

サンプル

リクエストサンプル

アクセストークンをヘッダで指定する場合

GET /api/v1/user_attributes/history HTTP/1.1
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxx

アクセストークンをクエリで指定する場合

・GET
GET https://api.opaas.io/api/v1/user_attributes/history?access_token=xxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "total_count": 185,
  "history": [
    {
      "action": "OFFER",
      "status": true,
      "service_id": "2000000000000000001000000000000a",
      "item_text": {},
      "key_list": [
        "accessibility", "address_line_1", "address_line_2", "age", "city", "country", "day_of_birth", "destination", "email", "entry_date", "family_name", "first_name", "food_and_drink_prohibition", "food_preference", "gender", "issue_date", "month_of_birth", "native_language", "original_address", "original_name", "passport_birth", "passport_country", "passport_gender", "passport_image", "passport_mrz", "passport_name", "passport_nationality", "passport_number", "priority_language", "qualification_for_stay", "state", "telephone", "term_of_validity", "user_interface", "year_of_birth", "zip"]
      "created_at": "2018-09-16T06:07:36.943Z"
    }, 
    {
      "action": "UPDATE",
      "status": true,
      "service_id": "2000000000000000001000000000000a",
      "item_text": {"destination": "Tokyo"},
      "key_list": ["destination"],
      "created_at": "2018-09-16T06:22:29.080Z"
    },
    以下略
  ]
}    

異常時（アクセストークンが有効でない場合）

HTTPステータスコード

401

レスポンス内容

{
  "error": "invalid_token",
   "error_description": "The access token provided is expired, revoked, malformed, or invalid for other reasons"
}

リクエストサンプル（パラメータが不正な場合）

・GET
GET https://api.opaas.io/api/v1/user_attributes/history?access_token=xxxxxxxxxx&per_page=a

レスポンスサンプル

異常時

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter per_page a must be positive integer value."
}

サービスドメイン一覧取得API ( GET api.opaas.io/service_domains)

サービスドメインの一覧を取得する。

サービスドメインは、特定の企業、団体などが扱う複数のサービスを集めたものであり、サービスは必ず一つのサービスドメインに属する必要がある。

認証ヘッダに付与されたアクセストークンに基づき、ユーザーIDを割り出す。

サービスドメイン一覧の取得を行うにはアクセストークンから割り出したユーザがサービスドメインに対する管理者権限を持つ必要がある。インフラ管理者はすべてのサービスドメインを、サービスドメインの管理者は自身が管理するサービスドメインの一覧を取得できる。

リクエストパラメータ

レスポンスパラメータ

サービスドメインのデータ構造

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/service_domains/?access_token=xxxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "total_num": 1,
  "start_pos": 1
  "service_domains": [{
    "service_domain_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name":"service domain 1",
    "title": "サービスドメイン１",
    "description": "サービスドメイン１の説明",
    "icon_url":"http://test.com",
    "tags": [ "test tag1", "test tag2" ],
    "reliability": 1,
    "email": "a@test.com",
    "telephone": "012-345-6789",
    "division": "test",
    "address": "Nagoya",
    "website": "http://web.com",
    "reg_date": "2018-09-08",
    "services": [
      "00000000000000000000010000000003",
      "00000000000000000000010000000007",
    ]
  }]
}

異常時（ユーザが管理者権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

)

{
  "status":"error",
  "message": "Request user is not administrator."
}

サービスドメイン情報取得API ( GET api.opaas.io/service_domains/{id})

サービスドメインの情報を取得する

認証ヘッダに付与されたアクセストークンに基づき、ユーザーIDを割り出す。

サービスドメインの取得を行うにはアクセストークンから割り出したユーザがサービスドメインに対する管理者権限を持つ必要がある。インフラ管理者または、サービスドメインの管理者のみがサービスドメインの情報を取得できる。

リクエストパラメータ

レスポンスパラメータ

GET api.opaas.io/service_domains/ の個々のサービスドメインのパラメータと同じ。

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/service_domains/{id}/?access_token=xxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "service_domain_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name":"service domain 1",
  "title": "サービスドメイン１",
  "description": "サービスドメイン１の説明",
  "icon_url":"http://test.com",
  "tags": [ "test tag1", "test tag2" ],
  "reliability": 1,
  "email": "a@test.com",
  "telephone": "012-345-6789",
  "division": "test",
  "address": "Nagoya",
  "website": "http://web.com",
  "reg_date": "2018-09-08",
  "services": [
    "00000000000000000000010000000003",
    "00000000000000000000010000000007",
  ]
}

異常時（ユーザが管理者権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

)

{
  "status":"error",
  "message": "Request user is not administrator."
}

サービスグループ一覧取得API ( GET api.opaas.io/service_groups )

サービスグループの一覧を取得する。サービスグループを利用することで、複数のサービスに対してパーソナルデータの提供を一括で設定できる。

認証ヘッダに付与されたアクセストークンに基づき、ユーザーIDを割り出す。

サービスグループ一覧の取得を行うにはアクセストークンから割り出したユーザがサービスグループに対する管理者権限を持つ必要がある。インフラ管理者はすべてのサービスグループを、サービスグループの管理者は自身が管理するサービスグループの一覧を取得できる。

リクエストパラメータ

レスポンスパラメータ

サービスグループのデータ構造

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/service_groups/?access_token=xxxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "total_num": 1,
  "start_pos": 1
  "service_groups": [{
    "service_group_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name":"service group 1",
    "title": "サービスグループ１",
    "description": "サービスグループ１の説明",
    "icon_url":"http://test.com",
    "reg_date": "2018-09-08",
    "services": [
      "00000000000000000000010000000003",
      "00000000000000000000010000000007",
    ]
  }]
}

異常時（ユーザが管理者権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

)

{
  "status":"error",
  "message": "Request user is not administrator."
}

サービスグループ情報取得API ( GET api.opaas.io/service_groups/{id})

サービスグループの情報を取得する

認証ヘッダに付与されたアクセストークンに基づき、ユーザーIDを割り出す。

サービスグループの取得を行うにはアクセストークンから割り出したユーザがサービスグループに対する管理者権限を持つ必要がある。インフラ管理者または、サービスグループの管理者のみがサービスグループの情報を取得できる。

リクエストパラメータ

レスポンスパラメータ

GET api.opaas.io/service_groups/ の個々のサービスグループのパラメータと同じ。

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/service_groups/{id}/?access_token=xxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "service_group_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name":"service group 1",
  "title": "サービスグループ１",
  "description": "サービスグループ１の説明",
  "icon_url":"http://test.com",
  "reg_date": "2018-09-08",
  "services": [
    "00000000000000000000010000000003",
    "00000000000000000000010000000007",
  ]
}

異常時（ユーザが管理者権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

)

{
  "status":"error",
  "message": "Request user is not administrator."
}

ユーザー登録API ( POST api.opaas.io/api/v1/users)

ユーザー登録を行うAPIである。 認証ヘッダに付与されたアクセストークンに基づき、サービスIDを割り出し、 サービスがパーソナルデータの編集権限を持つ場合のみ登録が可能である。

リクエストパラメータ

補足

GET accounts.opaas.io/oauth2/signup と異なり、本APIを実行することで直接ユーザの登録が行われる。その際に、login_id のメールアドレスの実在性のチェックは行われない。また、パスワードもこのAPIで直接設定する。

本APIはユーザのICカードの情報 (IDm) を設定することはできない。ユーザの IDm は PUT or PATCH api.opaas.io/api/v1/users/auth で編集する。

目的地等のパーソナルデータは PUT or PATCH api.opaas.io/api/v1/user_attirbutes で設定するため、本APIでは受け付けない

レスポンスパラメータ

登録に成功した場合、下記のパラメータがJSONのオブジェクト形式で返される。 なお、レスポンスパラメータにパスワードの情報は表示されない。

HTTPステータスコード

サンプル

リクエストサンプル

POST /api/v1/users
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type:application/json
Content-Length: 61

{"login_id":"a@test.com","password":"xxxxxx","user_status":0}

レスポンスサンプル

正常時

HTTPステータスコード

201

レスポンス内容

{
  "org_id": "xxxxxxxxxxxxxxxxxxxxxxxxxx",
  "login_id": "a@test.com",
  "user_status": "0"
}

異常時（認証エラー。アクセストークンのサービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "error": "error",
  "message": "Forbidden. Service xxxxxxx is not allowed to change user attribute."
}

異常時（パラメーターエラー。login_idのユーザが既に登録されている場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "{'login_id': ['Authori User with this xxxxxxxxxxxxxxxxxxxx already exists.']}"
}

異常時（パラメーターエラー。login_idがメールアドレスでない場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "{'login_id': ['Enter a valid email address.']}"
}

ユーザー認証方式取得API ( GET api.opaas.io/api/v1/users/auth)

ユーザーの認証情報である、IDm と user_status（現時点ではこのパラメータは未使用） の情報を取得するAPIである。本APIでパスワードを取得することはできない。

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出し、割り出したユーザの認証情報を変更する。

サービスがパーソナルデータの編集権限を持つ場合のみ情報の取得が可能である。

リクエストパラメータ

レスポンスパラメータ

idm と user_status の値がJSONのオブジェクト形式で返される。

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/users/auth?access_token=xxxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "idm": "zzzzzzzz",
  "user_status": "0"
}

ユーザー認証情報変更API ( PUT or PATCH api.opaas.io/api/v1/users/auth)

ユーザーの認証情報である、パスワードとIDmを設定するAPIである。パスワードのみ、IDmのみの変更も可能である。

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出し、割り出したユーザの認証情報を変更する。

サービスがパーソナルデータの編集権限を持つ場合のみ登録が変更である。

GET accounts.opaas.io/oauth2/resetpassword と異なり、本APIを実行することで直接ユーザのパスワードの変更が行われる。

本APIは、PUTとPATCHメソッドで同一の動作を行う。

リクエストパラメータ

レスポンスパラメータ

変更した場合、変更後のパラメータがJSONのオブジェクト形式で返される。

HTTPステータスコード

サンプル

リクエストサンプル

PUT /api/v1/users
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type:application/json
Content-Length: 70

{"old_password":"xxxxxxxx","new_password":"yyyyyyyy","idm":"zzzzzzzz"}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "idm": "zzzzzzzz"
}

パスワードを変更した場合、レスポンス内容には表示されない。

リクエストサンプル（パラメータを一つも設定しなかった場合）

PUT /api/v1/users
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type:application/json
Content-Length: 2

{}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{}

補足

パラメータを一つも設定しない場合でも、エラーとはしない。

異常時（パラメーターエラー。old_passwordに現在のパスワードと異なった値を指定した場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. Parameter old_password is invalid."
}

異常時（パラメーターエラー。既に登録されているIDMを指定した場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter error. IDm xxx already exist."
}

サービスへのパーソナルデータ提供ポリシー取得API ( GET api.opaas.io/api/v1/users/permissions )

自分自身のパーソナルデータをどのサービスに提供するかに関する設定状況を取得するAPIである。（ポータルアプリ等から呼び出されることを想定）

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。

サービスがパーソナルデータの編集権限を持つ場合のみ取得が可能である。

リクエストパラメータ

レスポンスパラメータ

結果はJSONのオブジェクト形式で下記の表の内容を返す。

user_authorities の配列の各要素（オブジェクト）の構造

attrs の配列の各要素（オブジェクト）の構造。attrs に表示されないパーソナルデータは、すべてtype, type_id の条件では許諾されていないものとみなされる。

HTTPステータスコード

サンプル

リクエストサンプル

・GET
GET https://api.opaas.io/api/v1/users/permissions/?access_token=xxxxxxxxx

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "user_authorities": [
    {
      "type": "reliability",
      "type_id": "1",
      "attrs": [
        {
          "attr_id": "gender",
          "authority": "1"
        },
        {
          "attr_id": "age",
          "authority": "0"
        }
      ]
    }
  ]
}

異常時（認証エラー時。サービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Service xxxxxxxx is not allowed to change user attribute."
}

サービスへの許諾変更API ( PUT or PATCH api.opaas.io/api/v1/users/permissions )

自分自身のパーソナルデータをどのサービスに提供するか設定する （ポータルアプリ等から呼び出されることを想定）

認証ヘッダに付与されたアクセストークンに基づき、サービスID、ユーザーIDを割り出す。

サービスがパーソナルデータの編集権限を持つ場合のみ設定が可能である。

本APIは、PUTとPATCHメソッドで同一の動作を行う。

リクエストパラメータ

レスポンスパラメータ

レスポンスパラメータ

変更した場合、変更後のパラメータがJSONのオブジェクト形式で返される。

HTTPステータスコード

サンプル

リクエストサンプル

PUT /api/v1/users/permissions
Host: api.opaas.io
Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type:application/json
Content-Length: 144

{"user_authorities":[{"type":"reliability", "type_id":"1", "attrs":[{"attr_id":"gender", "authority": "1"},{"attr_id":"age", "authority": 2}]}]}

レスポンスサンプル

正常時

HTTPステータスコード

200

レスポンス内容

{
  "user_authorities": [
    {
      "type": "reliability",
      "type_id": "1",
      "attrs": [
        {
          "attr_id": "gender",
          "authority": "1"
        },
        {
          "attr_id": "age", 
          "authority": 2
        }
      ]
    }
  ]
}

補足

上記の例の場合、type が reliability の設定状況のみ更新される（type が service, service_domain, service_group の設定状況には影響を与えない）。

異常時（認証エラー時。サービスがパーソナルデータの編集権限を持たない場合）

HTTPステータスコード

403

レスポンス内容

{
  "status": "error",
  "message": "Forbidden. Service xxxxxxxx is not allowed to change user attribute."
}

異常時（パラメータエラー時。user_authoritiesが存在しない場合）

HTTPステータスコード

400

レスポンス内容

{
  "status": "error",
  "message": "Parameter user_authorities is required"
}

モデル一覧

パーソナルデータ（user_attributes）

おもてなしパーソナルデータのモデルを記載します。

ルール情報（Rule）

ルール情報のモデルを記載します。

リクエストオプション（request_option）

ルール情報の中で外部サービスのAPI使用でセマンティクス変換する際に利用するリクエストオプションのモデルを記載します。

コード一覧

希望するユーザーインタフェースに関わるコード

アクセシビリティに関する情報

食の禁忌に関わるコード

食の嗜好に関わるコード