認証とトークン管理

本APIを呼び出すには、はじめにアクセストークンを取得する必要があります。取得の流れは、OAuth 2.0という標準的な認証の仕組みの中の「クライアント・クレデンシャルズ・グラント」（RFC 6749, 4.4）という方式に沿っています。発行された client_id と client_secret を使ってトークン発行APIを呼び出すだけで取得できます。

この認証は、外部システム（クライアントアプリケーション）そのものを認証するものであり、アプリを利用するエンドユーザー個人を認証するものではない点にご注意ください。

トークンの取得

POST {{APP_URL}}/api/ext/token
パラメータ 型 必須 説明
grant_type String ○ client_credentials 固定
client_id String ○ 発行されたクライアントID
client_secret String ○ 発行されたクライアントシークレット 
curl -X POST "{{APP_URL}}/api/ext/token" \
  -d grant_type=client_credentials \
  -d client_id={client_id} \
  -d client_secret={client_secret}

成功時レスポンス：

{
  "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": null
}

失敗時は 400 Bad Request または 401 Unauthorized などが返却されます。詳細は エラーコード一覧 を参照してください。

トークンの有効期限と再取得

アクセストークンの有効期間は 発行から24時間（86400 秒） です。期限が切れると、そのアクセストークンではAPIを利用できなくなります。

推奨実装パターン：毎リクエストごとにトークンを取得するのではなく、外部システム側でトークンの有効期限を管理し、期限切れのタイミングで再取得する構成を推奨します。トークン発行エンドポイントへの過剰なアクセスは、サーバー負荷の観点からも避けてください。

いずれの方式でも問題ありませんが、トークン発行APIへの呼び出し頻度は最小限にしてください。

リフレッシュトークンについて

本APIに リフレッシュトークンの機能はありません。トークン取得のレスポンスに refresh_token フィールドが含まれることはなく、アクセストークンの更新は、上記の通り client_credentials グラントによる再取得のみでおこなってください。

scope フィールドについて

scope は常に null が返却されます。本APIにはトークンごとの権限（スコープ）制御の仕組みはなく、発行されたアクセストークンで契約範囲のAPIすべてを利用できます。このフィールドは互換性のために残されているもので、外部システム側で参照する必要はありません。

複数接続元がある場合の client_secret

1つのSKUに対して複数のシステムから本APIに接続する場合、接続元ごとに個別の client_secret を発行します。新しい接続を追加する際は、営業担当までご連絡ください（詳細は はじめに を参照）。

アクセストークンの文字数について