OAuth 2.0への移行方法
このページでは、リダイレクトを用いたアプリケーションや独自のクライアントアプリケーションにおける既存の認証トークンの更新方法について説明します。APIバージョン1.1を使用できる条件は、次のとおりです：
- 複数のユーザーによってアプリケーションが使用されており、認証トークンの生成にユーザー名とパスワードが使用されている場合
- ユーザーが自身の認証トークンを入力している場合
リダイレクトを用いたアプリケーションの移行方法
前提条件
アプリケーションの所有者は、クライアントID、認証トークンのスコープ、対象のOAuthのスコープの情報をsupport@zohocampaigns.comに送信する必要があります。送信された情報がZoho Campaignsチームによって検証され、この情報を基にZoho Accountsで設定が行われます。検証の完了後、更新情報についてアプリケーションの所有者にメール通知が送信されます。
移行方法
リダイレクトを用いたアプリケーションの移行処理は、段階的に行います。
- Zoho Campaignsチームによる検証後、クライアントID、クライアントシークレット、認証トークンを使用して外部アプリケーションから移行APIを実行します。
- リクエスト内のパラメーターがすでに検証済みかどうかZoho Accountsによって検証が行われます。
- 検証の完了後、Zoho AccountsによってOAuthへのアクセスが許可され、アプリケーションのトークンが更新されます。
リクエストURL
リクエストのメソッド
POST
パラメーター
|
パラメーター
|
データの種類
|
説明
|
|
client_id
|
文字列
|
アプリケーションの登録時に取得したクライアントIDを指定します。
|
|
client_secret
|
文字列
|
接続するアプリケーション用に生成されたクライアントシークレットを指定します。
|
|
grant_type
|
文字列
|
値は「authtooauth」にする必要があります。
|
|
authtoken
|
文字列
|
使用中の認証トークンを指定します。
|
主なエラー
|
エラーコード
|
説明
|
|
invalid_grant
|
「grant_type」が「authtooauth」と指定されていません。
|
|
invalid_client
|
指定したクライアントIDが正しくありません。
（または）
有効なクライアントに対する認証トークンとOAuthとの関連付けが、Zoho Accountsで行われていません。
|
|
invalid_authtoken
|
指定した認証トークンが無効です。
（または）
認証トークンのスコープと共有された認証スコープが一致しません。
|
|
invalid_scope
|
指定したOAuthのスコープが無効です。
|
メモ：
- 実行可能な移行リクエストの上限は、1分間につき60件または1時間につき100件までです。
- 以前の認証トークンは、OAuthトークンが生成された次の日にシステムによって削除されます。
- クライアントによる認証トークンの指定の試行回数は、20回までです。この上限を超えると、システムによってクライアントがブロックされ、「access_denied」とエラーメッセージが表示されます。
独自のクライアントアプリケーションの移行方法
アプリケーションがサーバー上で独立して動作していて、ドメインやリダイレクトURLを設定していない場合、この移行方法に沿って設定することができます。
移行方法
独自のクライアントアプリケーションの移行処理は、段階的に行います。
- クライアントID、クライアントシークレット、認証トークン、対象のOAuthのスコープを使用して外部アプリケーションから移行APIを実行します。
- 認証トークンサービス名とOAuthのスコープが一致しているかどうかZoho Accountsによって検証が行われます。
- スコープの検証後、アプリケーションの所有者と認証トークンの所有者が同じかどうかZoho Accountsによって検証が行われます。
- 検証の完了後、Zoho Accountsによって外部アプリケーション用のOAuthトークンが生成されます。検証に失敗すると、システムによって「access_denied」とエラーメッセージが表示されます。
- Zoho Accountsから更新情報に関する通知がメールで送信されます。
リクエストURL
リクエストのメソッド
POST
パラメーター
|
パラメーター
|
データの種類
|
説明
|
|
client_id
|
文字列
|
アプリケーションの登録時に取得したクライアントIDを指定します。
|
|
client_secret
|
文字列
|
接続するアプリケーション用に生成されたクライアントシークレットを指定します。
|
|
grant_type
|
文字列
|
値は「authtooauth」にする必要があります。
|
|
authtoken
|
文字列
|
使用中の認証トークンを指定します。
|
|
scope
|
文字列
|
Zoho CampaignsのデータにアクセスするOAuthのスコープを指定します。Zoho Campaignsのスコープの詳細については、Zoho CampaignsのREST APIのヘルプに記載されている認証トークンのセクションをご参照ください。
|
主なエラー
|
エラーコード
|
説明
|
|
invalid_grant
|
「grant_type」が「authtooauth」と指定されていません。
|
|
access_denied
|
指定した認証トークンがすでにOAuthトークンの生成に使用されています。
|
|
invalid_client
|
指定したクライアントIDが正しくありません。
|
|
invalid_authtoken
|
指定した認証トークンが無効です。
|
|
invalid_scope
|
指定したOAuthのスコープが無効です。
|
メモ：
- 実行可能な移行リクエストの上限は、1分間につき25件または1時間につき60件までです。
- 以前の認証トークンは、OAuthトークンが生成された次の日にシステムによって削除されます。
エラーコード
エラーコードの詳細については、こちらのページをご参照ください。