OAuthトークンAPIの生成

OAuthトークンAPIの生成

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

TrainerCentral APIでは、要求の認可と認証にOAuth 2.0プロトコルを使用します。OAuth 2.0は、サードパーティ製アプリケーションへの制限付きアクセスを可能にする、トークンベースの認可フレームワークです。ユーザーに代わって仲介役として機能し、ユーザーが認証したリソースのみにアクセスを許可し、それ以外へのアクセスをブロックすることで、制御されたアクセスを提供します。これにより、ユーザーデータのセキュリティが強化されます。

OAuthトークンの生成手順

1. アプリケーションの登録（新しいクライアントとして）

1. Web ブラウザーでhttps://accounts.zoho.com/developerconsoleにアクセスします。

2. ［クライアントIDの追加］をクリックし、以下の詳細を入力します。

  • ［クライアント名］は、アプリケーションの名前です。
  • ［クライアントドメイン］は、アプリケーションにアクセスするためのURLです。
  • ［リダイレクトURL］は、認可が成功した後にユーザーがリダイレクトされるアプリケーションのコールバックURLです。サーバーは、リダイレクトURLのクエリー文字列としてcodeパラメーターを返します。このコードは、アクセストークンと更新トークンの取得に使用されます。

3. 最後に、［作成］をクリックします。

4. 登録が完了すると、アプリケーション固有のOAuth認証情報であるクライアントIDとクライアントシークレットが発行されます。これらの認証情報は、TrainerCentralとアプリケーションの双方で共有されます。

2. グラントトークンの生成

1. 認可URL https://accounts.zoho.com/oauth/v2/auth に、以下のパラメーターの値をクエリー文字列として指定します。

認可URLに渡す、大文字と小文字が区別される必須パラメーターは、以下の表のとおりです。

パラメーター 説明
scope 拡張機能に必要なスコープです。
client_id クライアント登録時に取得したクライアントIDです。
state コールバックと関連する認可要求を対応付けるために生成された値です。
response_type 'code'


redirect_uri クライアント登録時に指定したリダイレクトURLです。
access_type アクセスタイプはonlineまたはofflineです。

prompt
値は同意にする必要があります。

2. ユーザー認可ページで同意を求められます。［承諾］をクリックします。
メモ：このコードは2分間有効で、アクセストークンと更新トークンの取得に使用できます。

3.アクセストークンと更新トークンの生成

TrainerCentralのAPIにアクセスする最後の手順は、アクセストークンで認証することです。上記のグラントトークンの生成で取得した認可コードを使用して、アクセストークンと更新トークンを取得できます。

メモ：このコードは1回のみ使用できます。コードの有効期限が切れた場合は、再生成する必要があります。

1. POST要求を以下のURL https://accounts.zoho.com/oauth/v2/token に、以下の表のパラメーターを使用して送信します。

パラメーター 説明
code グラントトークン生成時に取得した認可コード。
client_id クライアント登録時に取得したクライアントID。
client_secret クライアント登録時に取得したクライアントシークレット。
redirect_uri クライアント登録時に指定したリダイレクトURL。
grant_type authorization_code
scope 拡張機能に許可するスコープを指定します。
state コールバックと関連する認可要求を対応付けるために生成される値。真正性を確保するため、処理全体を通じて同じ値に保つ必要があります。

2. 認可に成功すると、TrainerCentralはアプリケーションに次の情報を含む応答を返します。

  • expires_in:トークンが有効な期間（ミリ秒）。
  • token_type: トークンの種類。この場合は bearer です。
  • access_token:ユーザーのアクセストークン。このトークンは最終的なAPI呼び出しに使用でき、有効期間は1時間のみです。
  • refresh_token:トークンが期限切れになった場合に使用するリフレッシュトークン。このトークンは永続的で、アプリを更新して新しいアクセストークンを取得するために最大20回使用できます。

4. アクセストークンの再生成

アクセストークンには有効期間があります。ほとんどの場合、アクセストークンは1時間で期限切れになります。この期間中、アクセストークンは何度でも使用できます。アクセストークンの期限が切れたら、リフレッシュトークンを使用して新しいアクセストークンを生成できます。

パラメーター 説明
client_id クライアント登録時に取得したクライアントID。
client_secret クライアント登録時に取得したクライアントシークレット。
redirect_uri クライアント登録時に指定したリダイレクトURL。
grant_type refresh_token
refresh_token アクセストークン生成時に取得したリフレッシュトークン。（ステップ3）
scope 拡張機能に許可するスコープを指定します。

OAuthトークンを使用したリクエストのサンプル

REST APIを呼び出す際、アクセストークンをヘッダーとして渡す必要があります。アクセストークンはリクエストパラメーターではなく、リクエストヘッダーとしてのみ渡せる点に注意してください。

必須ヘッダーの一覧は以下のとおりです。

ヘッダー名 ヘッダー値
Authorization Zoho-oauthtoken<space>{{access token}}
contentType application/json

5. リフレッシュトークンの取り消し

アプリケーションにアクセスする必要がなくなった場合は、以下のようにアクセスを取り消せます。

例：クエリー文字列

https://accounts.zoho.com/oauth/v2/token/revoke?refresh_token=1000.dd7e47321d48b8a7e312e3d6eb1a9bb8.b6c07ac766ec11da98bf6a261e24dca4

OAuth 2.0について詳しくは、こちらをご参照ください。