Senju Service Manager では、Senju Service Manager のデータにアクセス可能な WEBAPI を提供します。
Senju Service Manager のデータにアクセス可能な WEBAPI を API 連携機能と表現します。
API 連携機能は、WEB サーバーApache と Python で作成された WEB アプリケーションで構成されます。

すべての API アクセスは、HTTP(S)のリクエストを介して行われます。
すべてのリクエストとレスポンスのメディアタイプは application/json です。
JSON形式でダブルクォーテーションやバックスラッシュなどの文字を使用する場合は，エスケープする必要があります。

Senju Service Manager の API は、以下の方式で認証・認可を行います。

• Senju Service Manager ログイン時と同じ認証を行い、認証に成功した場合にアクセストークンを発行します。
• アクセストークンをリクエストヘッダに指定し、Senju Service Manager の API を実行します。
  

注意：認証方式が「SSM 基本認証」のユーザーのみがアクセストークンを発行できます。

アクセストークン・リフレッシュトークンの発行

Senju Service Manager ログイン時の認証を行い、認証に成功した場合はアクセストークン・リフレッシュトークンを発行します。

cURL を使用する場合のコマンド例を以下に記載します。

curl -X POST \
  https://localhost:49152/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<ユーザーID>","password":"<パスワード>"}'

注意：windows上でcURLを実行する場合は、以下のように読み替えてください。

• シングルクォートをダブルクォートに置換する
• 括弧内のダブルクォートをエスケープする

curl -X POST \
  https://localhost:49152/auth/login \
  -H "Content-Type: application/json" \
  -d "{\"username\":\"<ユーザーID>\",\"password\":\"<パスワード>\"}"

認証が成功した場合、アクセストークン・リフレッシュトークンが JSON 形式で返却されます。

{
  "access_token": "<アクセストークン>",
  "refresh_token": "<リフレッシュトークン>"
}

アクセストークン・リフレッシュトークンは Senju Service Manager の API 実行時にリクエストヘッダに指定するため、クライアントで管理する必要があります。

アクセストークンの更新

アクセストークンの有効期限が切れた場合、アクセストークン更新APIでアクセストークンを更新する必要があります。
以下のリクエストを送信することにより、アクセストークンを更新できます。

• POST メソッドを指定します
• URLに https://localhost:49152/auth/refresh を指定します
• Authorization ヘッダーに Bearer 方式でリフレッシュトークンを指定します

curl -X POST \
  https://localhost:49152/auth/refresh \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <リフレッシュトークン>'

アクセストークンの更新が成功した場合、更新後のアクセストークンが JSON 形式で返却されます。

{
  "access_token": "<アクセストークン>"
}

注意：

• 本 API を実行した場合、更新前のアクセストークンは無効化され使用できなくなります
• Senju Service Manager の API 実行時は更新後のアクセストークンをリクエストヘッダに指定してください

アクセストークンの無効化

有効期限内のアクセストークンを手動で無効化する場合は、アクセストークン無効化APIを利用します。
以下のリクエストを送信することにより、アクセストークンを無効化できます。

• DELETE メソッドを指定します
• URLに https://localhost:49152/auth/revoke_access を指定します
• Authorization ヘッダーに Bearer 方式でアクセストークンを指定します

curl -X DELETE \
  https://localhost:49152/auth/revoke_access \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <アクセストークン>'

アクセストークンの無効化が成功した場合、以下のレスポンスが JSON 形式で返却されます。

{
  "message": "access_token revoked"
}

リフレッシュトークンの無効化

有効期限内のリフレッシュトークンを手動で無効化する場合は、リフレッシュトークン無効化APIを利用します。
以下のリクエストを送信することにより、リフレッシュトークンを無効化できます。

• DELETE メソッドを指定する
• URLに https://localhost:49152/auth/revoke_refresh を指定する
• Authorization ヘッダーに Bearer 方式でリフレッシュトークンを指定する

curl -X DELETE \
  https://localhost:49152/auth/revoke_refresh \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <リフレッシュトークン>'

リフレッシュトークンの無効化が成功した場合、以下のレスポンスが JSON 形式で返却されます。

{
  "message": "refresh_token revoked"
}

Senju Service Manager の API でエラー発生時、エラー情報がjson形式のレスポンスとして返却されます。

{
    "message": "<メッセージ>, path=<エラー発生箇所>"
}

レスポンスボディの path 以降の内容は、リクエストボディの JSON に不備があった場合のみ出力されます。
path以降の内容は下記のように出力されます。

{
    "message": "[] is too short, path=deque(['users', 0, 'account_data', 'group_list'])"
}

• 意味
  1 人目のアカウント情報「所属グループ」に値が1 件も指定されていません。
• 説明
  
  • users 後の0 は何人目のユーザー情報に不備があるかを示します
    (0 始まりのため、1 人目のユーザー情報に不備があります)
    
  • account_data は、アカウント情報に不備があることを示します
    
  • group_list は、所属グループの指定に不備があることを示します

認証・認可用エンドポイント