ドキュメント The Livelox public API OAuth2によるユーザー委任を通じたAPIへのアクセス

OAuth2によるユーザー委任を通じたAPIへのアクセス

ユーザー固有のデータにアクセスするエンドユーザー向けのアプリケーションでは、APIキーを使用するのではなく、ユーザー自身がAPIへのアクセス権限を認可する必要があります。これにはOAuth2プロトコルが使用され、PKCE対応認可コードフロー（Authorization Code with PKCE Flow）が適用されます。これにより、ユーザーは一度Liveloxのウェブサイトにリダイレクトされ、そこでご自身のアプリケーションが彼らに代わってLiveloxにアクセスすることを許可する形になります。

OAuth2 エンドポイント

認可エンドポイント（Authorization endpoint）: https://api.livelox.com/oauth2/authorize
トークンエンドポイント（Token endpoint）: https://api.livelox.com/oauth2/token
トークン失効エンドポイント（Token revocation endpoint）: https://api.livelox.com/oauth2/revoke
ユーザー情報エンドポイント（User info endpoint）: https://api.livelox.com/oauth2/userinfo

クライアントID（Client ID）

OAuth2プロトコルでは、呼び出し元アプリケーションの識別子として client_id を使用します。弊社からお客様のアプリケーションに対して client_id（通常はアプリケーション名）を割り当てます。

スコープ（Scopes）

スコープとは、アプリケーションによるユーザーアカウントへのアクセスを制限するためにOAuth2で用いられる仕組みです。アプリがユーザーに代わって実行できる正確なアクションや、アクセスできるデータを定義します。Liveloxでは以下のスコープが使用されます。

events.import - アプリケーションがユーザーに代わって、Liveloxイベントにコース設定情報をインポートできるようにします
routes.import - アプリケーションがユーザーに代わって、LiveloxにGPSルートをインポートできるようにします

トークンの有効期限（Token life lengths）

認可コードの有効期限は10分間です。アクセストークンは24時間有効です。リフレッシュトークンに有効期限はありません（無期限）。ユーザーはLiveloxのアカウント設定から、いつでもトークンの失効やスコープの変更を行うことができます。

一般的なワークフロー（Typical workflow）

以下のステップは、アプリケーションがLiveloxとやり取りをして、ユーザーから代理でのAPIリクエスト実行の同意（認可）を得るまでの流れを示しています。ユーザーの認可を必要とするLivelox APIリクエストを実行するには、事前にアプリケーションがこの同意を得ておく必要があります。

Liveloxの同意ページへリダイレクトします：https://api.livelox.com/oauth2/authorize?response_type=code&scope={scope}&redirect_uri={redirect_uri}&client_id={client_id}&state={state}&code_challenge={code_challenge}&code_challenge_method=S256
- redirect_uri: 認証コードを受け取るために、ご自身のアプリにリダイレクトして戻すためのアドレスです。モバイルアプリの場合は、カスタムURLスキームの手法を使用してください：Android、iOS。
- state: 認可リクエストと認可サーバーからのレスポンスの間で、アプリケーションが状態（ステート）を維持するために使用する任意の文字列を指定します。詳細はこちらをご覧ください。
- code_challenge: BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) です。ここで使用する code_verifier は、アプリ側で設定し、ステップ4で送信する検証用キーです。詳細はこちらをご覧ください。
ユーザーがまだログインしていない場合は、同意ページでLiveloxのユーザー名とパスワードを入力します。その後、ユーザーはアプリがLiveloxにデータを投稿することを承認します。
ユーザーがご自身のアプリにリダイレクトされます：{redirect_uri}?code={code}&state={state}
- redirect_uri: ステップ1で指定したものと同じURL
- code: 認可コード（ステップ4で使用）
- state: ステップ1で指定したものと同じ文字列
アプリがLivelox APIを通じて認証キー（トークン）を生成します。

POST https://api.livelox.com/oauth2/token を、www-form-urlencoded形式のボディ grant_type=authorization_code&code={code}&client_id={client_id}&code_verifier={code_verifier}&scope={scope} で送信します。
- code: ステップ3で取得したもの
- code_verifier: ステップ1で設定したもの
レスポンスには access_token、refresh_token、expires_in（有効期限）などが含まれます。これらをアプリ側で保存してください。
access_token の有効期限が切れていない間は、APIを呼び出す際に HTTPの Authorization ヘッダーにこれを含めて使用します。

Authorization: Bearer {access_token}
access_token の有効期限が切れると、サーバーは HTTP 403 レスポンスを返します。その際は refresh_token を使用して新しい access_token を生成してください。

POST https://api.livelox.com/oauth2/token を、www-form-urlencoded形式のボディ grant_type=refresh_token&client_id={client_id}&refresh_token={refresh_token} で送信します。
- refresh_token: ステップ4で保存したもの