認可 (Authorization)

概要

eBay APIの呼び出しを認可するために、以下の2つの方法がサポートされています。

OAuth — すべてのeBay RESTful APIは、アプリケーションおよびユーザーの認可にOAuth 2.0プロトコルを使用します。OAuthは、オンライン取引の安全性を確保するための業界標準です。eBay RESTfulインターフェースに対して行うすべてのリクエストには、有効なアクセストークンを提供する必要があります。OAuthアクセストークンは、リクエストが有効なアプリケーションから送信されていること、およびそのアプリケーションがリクエストを実行するためのユーザーの認可を得ていることをeBayに対して証明します。OAuthトークンは、eBayの従来のAPI (Traditional APIs) でも使用可能です。
重要: Trading APIのような従来のAPIを使用する場合でもOAuthの使用を推奨しますが、eBayの従来のAuth'n'Authプロセスも古いアプリケーション向けに引き続き利用可能です。

アプリケーションに割り当てられたOAuthスコープにより、特定のAPIリソースやメソッドへのアクセスが可能になります。有効なOAuthトークンであっても、ターゲットとなるメソッドが必要とするスコープで生成されたものでなければ、リクエストを正常に認可することはできません。

アプリケーションのOAuthスコープは、「Application Keys」ページで確認できます。
Auth’n’Auth — eBayの従来のAPIで使用されている認証および認可技術です。

OAuthスコープの利用

OAuthスコープは、アプリケーションに対して様々なメソッドやリソースへのアクセス権を付与します。リクエストの認可に使用するOAuthトークンは、アクセスしようとしているメソッドやリソースが必要とするOAuthスコープを持っている必要があります。

どのタイプのOAuthアクセストークンを生成する場合でも、生成されたトークンでアクセスする機能に対応するスコープのセットを指定する必要があります。

つまり、有効なOAuthトークンであっても、ターゲットとなるメソッドが必要とするスコープで生成されたものでなければ、リクエストを正常に認可することはできません。

スコープの割り当て
スコープとアクセス
アクセストークン発行時のスコープ指定
アプリケーションに割り当てられたスコープリストの取得
スコープと付与フロー
スコープとリフレッシュトークン

スコープの割り当て

Developers Programにサインインすると、SandboxおよびProduction環境の両方の アプリケーションキー (Application Keys) を生成できます。

生成された各アプリケーションキーセットには一連の スコープ (Scopes) が割り当てられ、各スコープはアプリケーションに対して異なるAPIメソッド、リソース、機能へのアクセス権を付与します。

開発者ポータルの Application Keys ページを通じて、アプリケーションキーセットに割り当てられたスコープのセットを確認できます。

Application Keys ページ内の右下に表示されている OAuth Scopes リンクをクリックすると、アプリケーションのスコープリストを取得できます。

スコープとアクセス

アプリケーションキーセットに割り当てられた各スコープは以下を決定します。

そのスコープでアクセス可能なリソースのセット。
そのスコープで実行可能な操作のセット。

新しいトークンを生成するために使用するリクエストには、そのトークンで呼び出す予定の すべての メソッドへのアクセスを許可するスコープのリストを含める必要があります。

アプリケーションに必要なスコープを確認するには、アプリケーションで使用する各メソッドのAPIドキュメントの OAuth scope セクションを参照してください。そして、呼び出す各メソッドに記載されているスコープのうち、少なくとも1つを含めてアクセストークンを発行します。これにより、各アクセストークンには、すべてのリクエストを行うために必要な認可が含まれることになります。

アクセストークン発行時のスコープ指定

どのフローを使用してOAuthアクセストークンを生成する場合でも、トークン生成リクエストには常に有効なスコープのリストを提供する必要があります。

Identity APIを使用してトークンを発行する場合、アプリケーションキーセットに属するスコープは scope クエリパラメータを通じて渡されます。スコープクエリパラメータを通じてスコープを渡す方法の詳細については、「クライアントクレデンシャル付与フロー」および「認可コード付与フロー」のセクションを参照してください。

アプリケーションに割り当てられたスコープリストの取得

アプリケーションキーのセットを作成すると、アプリケーションキーセットに一連のスコープが割り当てられます。

Developers Programは、SandboxおよびProduction環境の両方のサンプルリクエストを提供しており、これらのサンプルを使用してアプリケーションに割り当てられたスコープの文字列を取得できます。

SandboxまたはProduction環境のアプリケーションキーセットに割り当てられたスコープのリストを取得する手順は以下の通りです。

eBay Developer Programにログインし、Your Account > Application Keys に移動します。
ターゲットとする環境のClient IDの横に表示されている User Tokens リンクをクリックします。

User Tokens (eBay Sign-In) ページが表示されます。Get a Token from eBay via Your Application の見出しの下で、RuNameを設定すると、RuName ボックスが表示されます。

完全なサンプルリクエストを表示するには、See all リンクをクリックします。サンプルから scope パラメータの完全な値をコピーして、アプリケーションに割り当てられたスコープのリストを取得します。
トークンサーバーへのリクエストで送信する際は、scope の値をURLエンコードします。

この方法でスコープをコピーすると、アプリケーションで必要なスコープよりも大きなセットを使用することになる可能性があります。ユーザースコープは権限の付与を意味するため、ユーザーはアプリケーションを使用する前に、スコープが示すこれらすべての権限に同意する必要があります。

Sandbox環境とProduction環境では、アプリケーションに対してサポートされるスコープのセットが異なる可能性があることに注意してください。トークンリクエストでスコープの文字列を提供する際は、ターゲットとする環境にスコープを一致させるようにしてください。

スコープと付与フロー

eBayトークンサービスは、2つの異なる付与フロー (Grant Flows) を通じてアクセストークンを発行します。

クライアントクレデンシャル付与フロー (Client credentials grant flow) は、新しい アプリケーションアクセストークン (Application access token) を発行します。
認可コード付与フロー (Authorization code grant flow) は、新しい ユーザーアクセストークン (User access token) を発行します。

各フローはアクセストークンを生成するために異なるプロセスを使用し、使用する付与フローはアプリケーションで使用されるeBayメソッドに割り当てられた「スコープ」に依存します。

クライアントクレデンシャル付与フローはアプリケーションアクセストークンを発行するために使用され、アプリケーションが特定のeBayユーザーに固有ではないリソースやデータにアクセスまたは操作する場合に使用できます。アプリケーションアクセストークンを必要とするメソッドの好例として、メタデータや分類 (Taxonomy) の呼び出しが挙げられます。

認可コード付与フローはユーザートークンを発行するために使用され、特定のeBayユーザーに固有のデータを投稿または返すメソッドに使用されます。アプリケーションアクセストークンよりもユーザートークンを必要とするメソッドの方がはるかに多く存在します。各メソッドのリファレンスページにある OAuth scope セクションには、そのメソッドに必要なトークンの種類が示されています。

スコープとリフレッシュトークン

ユーザーアクセストークンを作成する際、同意リクエストにスコープのリストを提供する必要があります（詳細は「アプリケーションに割り当てられたスコープリストの取得」を参照）。詳細については、「認可コード付与フロー」のセクションを参照してください。

リフレッシュトークンをリクエストする場合、以下のいずれかを選択できます。

オプションの scope パラメータを含めてスコープのリストを提供する。
scope パラメータを含めず、同意リクエストに含まれていたスコープのセットをデフォルトとする。

OAuthアクセストークンの取得

アクセストークンの発行

すべてのeBay REST APIは、アプリケーションおよびユーザーの認可に OAuth 2.0プロトコルを使用します。OAuthはオンライン取引の安全性を確保するための業界標準であり、eBay RESTインターフェースに対して行うすべてのリクエストに有効なアクセストークンを提供する必要があります。

OAuth アクセストークン は、リクエストが有効なアプリケーションから送信されていること、およびそのアプリケーションがリクエストを実行するためのユーザーの認可を得ていることをeBayに対して証明します。

有効なアクセストークンを取得したら、それを使用してリクエストを認可します。

重要: アクセストークンを作成するために必要なOAuth 2.0クライアントクレデンシャルを取得するには、有効なeBay Developer Programアカウントが必要です。

アクセストークンの発行

eBayトークンサービスは、2つの異なる付与フローを通じてアクセストークンを生成、または 発行 (mints) します。

クライアントクレデンシャル付与 (Client credentials grant) フローは、アプリケーションが所有するリソースにアクセスするために使用できる新しい アプリケーションアクセストークン (Application access token) を発行します。
認可コード付与 (Authorization code grant) フローは、ユーザーが所有するリソースにアクセスするために使用できる新しい ユーザーアクセストークン (User access token) を発行します。

eBay OAuthクライアントライブラリ

eBayは、アプリケーションでのOAuthトークン発行を迅速に実装するために使用できるいくつかのクライアントライブラリを提供しています。

アプリケーションへのOAuthの実装

以下のトピックでは、2つの付与フローそれぞれを使用してOAuthトークンの発行を実装する方法について説明します。

クライアントクレデンシャル付与フロー
認可コード付与フロー

redirect_uri値の取得

ユーザーアクセストークンを取得するリクエストには、ユーザーが権限付与リクエストを完了した後にリダイレクトされるURLとして、redirect_uri 値が必要です。URLの代わりに、OAuthフローでは、eBayが生成してアプリケーションに割り当てるカスタムの RuName 値が必要です。

RuName値について

RuNameには、承諾URL (Accept URL) と拒否URL (Reject URL) の値など、いくつかの情報が紐付けられており、ユーザーが権限付与リクエストにどのように応答したかに応じて、異なるページをカスタマイズして表示することができます。

アプリケーションには2つのユニークなRuName値があり、それぞれSandboxまたはProduction環境のいずれかをサポートします。

RuName値の取得

RuNameを取得する手順は以下の通りです。

eBay Developer Programにログインし、Your Account > Application Keys に移動します。
Client IDの横に表示されている User Tokens リンクをクリックします。

Get a Token from eBay via Your Application ドロップダウンが表示されます。

クリックすると設定画面が表示されます。
RuName（eBay Redirect URL name とも呼ばれます）をまだ作成していない場合は、You have no Redirect URLs. Click here to add one. というリンクをクリックします。
Confirm the Legal Address for the Primary Contact or Business フォームが表示されます。
フォームに入力して連絡先情報を確認し、Continue to create RuName ボタンをクリックします。

結果の画面にRuName値が表示されます。

アプリケーションアクセストークンのみを使用する場合は、残りのRuNameフィールドに入力する必要はありません。プライバシーポリシーへのURLや、承諾および拒否URLは、ユーザーアクセストークンを使用する場合にのみ必要です。

ユーザートークンを使用する場合は、以下で詳しく説明するように、RuNameフォームの残りの部分に入力してください。

RuName値の設定

Get a Token from eBay via Your Application ボックスには、ユーザートークン用のRuNameを設定するさまざまなフィールドが含まれています。

RuNameを使用してユーザートークンを作成する前に、以下のフィールドを設定してください。

フィールド名	説明
Display Title	クライアント付与フロー中に、eBayが Grant Application Access ページの先頭に表示するタイトルです。
Privacy Policy URL	プライバシーポリシーをホストしているURLを入力します。このポリシーには、ユーザーがアプリケーションに許可を与えた際にアクセスできるeBay情報をどのように使用するかが記載されています。
Auth Accepted URL	ユーザーがアプリケーションに対して代理で行動するために必要な権限を付与した場合、eBayはユーザーをこのURLにリダイレクトします。
Auth Declined URL	ユーザーがアプリケーションに必要な権限を付与しなかった場合、eBayはユーザーをこのURLにリダイレクトします。

Base64エンコードされたクレデンシャルの生成

APIリクエストを認可するには、Authorization ヘッダーの値を、アプリケーションのOAuthクレデンシャルをBase64エンコードした値に設定します。

クレデンシャルをエンコードする前に、client_id 値、コロン、そして client_secret 値を並べて結合します。

具体的には、以下をBase64エンコードします： <client_id>:<client_secret>

Authorization ヘッダーの値には、Base64エンコードされたクレデンシャルの前に "Basic " という単語とスペースを付けます。以下に例を示します。

Basic <B64-encoded_oauth_credentials>

アプリケーションキーの取得ページに移動すると、ユーザーインターフェースを通じて、短寿命（2時間以下）のアプリケーションアクセストークンまたはユーザーアクセストークンを素早く生成できます。

開発者ポータル経由でのアプリケーションアクセストークンの取得

アプリケーションアクセストークンを取得する手順は以下の通りです。

eBay開発者ポータルの Application Keys ページに移動します。
トークンを生成したい環境の App ID リストの横にある User Tokens リンクをクリックします。
表示されたページで、Get OAuth Application Token リンクをクリックします。

このアプリケーションアクセストークンを使用して、トークンが生成された環境のAPIへリクエストを行うことができます。

開発者ポータル経由でのユーザーアクセストークンの取得

開発者ポータルを通じてユーザーアクセストークンを生成することも可能です。

eBay開発者ポータルの Application Keys ページに移動します。
App ID 値（ProductionまたはSandbox環境）の横にある User Tokens リンクをクリックします。
Get a User Token Here セクションで、OAuth (new security) ラジオボタンを選択し、サインインボタンをクリックします。
- Productionユーザートークンを生成する場合は、実際のeBayユーザーのクレデンシャルが提供されます。
- Sandboxユーザートークンを生成する場合は、Sandboxテストユーザーのクレデンシャルが提供されます。
Grant Application Access ページ（Accept URL設定によって決定されます）で、Agree ボタンをクリックします。
ユーザーアクセストークンが返されます。

このユーザートークンを使用して、トークンが生成された環境のAPIへリクエストを行うことができます。ただし、ユーザーアクセストークンは短寿命であるため、有効期限切れ後にリフレッシュトークンを使用して更新するなど、プログラムによって自動的にユーザートークンを生成することが推奨されます。「リフレッシュトークンを使用したユーザーアクセストークンの更新」のセクションを参照してください。

OAuthのベストプラクティス

このトピックでは、eBayのOAuth実装を扱う際の詳細とベストプラクティスについて説明します。

セキュリティとOAuthトークン

アクセストークンは 短寿命 であり（セキュリティ上の理由からすぐに期限切れになります）、一方でリフレッシュトークンは長期間有効です。ただし、リフレッシュトークンの機能は制限されており、新しいアクセストークンを取得するためにのみ使用できます（リクエストの認可には使用できません）。

リフレッシュトークンで呼び出しを行うことはできませんが、機密情報として扱い、安全な場所に保管する必要があります。アクセストークンやクライアントシークレットと同様に、リフレッシュトークンの値が漏洩したと考えられる場合は、悪用による影響を制限するために直ちに対策を講じる必要があります。

重要: OAuthトークンとクレデンシャルは機密情報として扱う必要があり、共有したり公に公開したりしてはいけません。最高のパフォーマンスとセキュリティのために、アプリケーションはアクセストークンをメモリ上に保持し、期限切れになるまで再利用するべきです。

Sandboxでのテスト

OAuthトークンリクエストで発行したトークンは、そのトークンが発行された環境でのみ機能します。ユーザーアクセストークン用のトークンリクエストは3つあり、各リクエストのターゲット環境を確実に一致させる必要があります。

ユーザーアクセストークンでテストを行う場合、Sandboxテストユーザーアカウントから「同意」を得る必要があります。ただし、テストが完了したら、ProductionのOAuthクレデンシャルとProductionのURLを使用してアクセストークンフローを再度実行し、Productionのアクセストークンを取得してください。これを行うには、「サードパーティの同意の取得」トピックで説明されているように、同意リクエストのステップからプロセスを最初からやり直します。ここでの違いは、Sandboxテストアカウントではなく、アプリの実際のユーザーから同意を得ることです。

OAuthトークンのベストプラクティス

以下のリストは、アクセストークンとそのレート制限を扱う際のベストプラクティスを示しています。

アクセストークンは短寿命であり、発行されてから比較的すぐに期限切れになります。これは、悪意のあるユーザーによるアクセストークンの乱用を防ぐためのセキュリティ対策です。アクセストークンは期限切れになるまで使用し、その後、アプリケーションアクセストークン用のクライアントクレデンシャル付与、またはユーザーアクセストークン用のリフレッシュトークン付与を使用して新しいトークンを作成してください。
リフレッシュトークンは長寿命ですが、予期せず取り消されることがあります。例えば、関連付けられたユーザーがeBayユーザー名を変更したり、同意を取り消したりする可能性があります。さらに、eBayはさまざまな理由でトークンを取り消すことがあります。これらのシナリオを考慮し、アプリケーションはユーザーアクセストークンの取り消しを適切に処理する必要があります。
リフレッシュトークンは長期間有効です。リフレッシュトークンが期限切れになった場合、それぞれのユーザーに対して新しいユーザーアクセストークンを発行するために、再度権限付与リクエストを行う必要があります。
アクセストークンは短寿命ですが、eBayは各タイプの付与リクエストで発行できるトークンの数に対して厳格な日次レート制限を設けています。アプリケーションがOAuthトークンのリクエスト制限内に収まるようにしてください。
アプリケーションの現在の機能に必要なすべてのスコープに加え、将来的に追加予定の機能に必要なスコープを使用してユーザーアクセストークンを作成してください。既存のユーザーアクセストークンに新しいスコープを追加するには、各ユーザーからの新しい権限付与が必要となり、ユーザーが複数の同意リクエストを嫌がる可能性があります。
アプリケーションが必要とするスコープのみを使用してトークンを作成してください。例えば、対応する「表示・管理スコープ (view and manage scope)」が指定されている場合、読み取り専用スコープを指定する必要はありません。
悪意のある人物によるハッキングや、不正または違法な行為への利用を防ぐため、OAuthクレデンシャルとリフレッシュトークンは安全なサーバーに保管してください。

アクセストークンのレート制限

eBay APIの不正利用を防ぐため、各アプリケーションには24時間あたりにOAuthエンドポイントに対して行えるリクエスト数に制限があります。アプリケーションに割り当てられたリクエスト数は、そのアプリケーションの レート制限 (rate limit) と呼ばれます。

OAuthレート制限は、アプリケーションがOAuthアクセストークンを発行するために使用するエンドポイント (https://api.ebay.com/identity/v1/oauth2/token) に割り当てられており、grant_type 値ごとにレート制限が異なります。以下の表は、異なる grant_type 値に対するレート制限を示しています。

Grant type	Access Token Type	Rate Limit
Client credentials grant (grant_type = `client_credentials`)	Application access token	1,000 リクエスト/日
Authorization code grant (grant_type = `authorization_code`)	User access token	10,000 リクエスト/日
Refresh token grant (grant_type = `refresh_token`)	User access token	50,000 リクエスト/日

クライアントクレデンシャル付与フロー

このトピックでは、クライアントクレデンシャル付与フロー (Client credentials grant flow) を使用してOAuthアクセストークンを発行する方法について説明します。

このプロセスから取得されるアクセストークンは、アプリケーションアクセストークン (Application access token) と呼ばれます。

OAuthクライアントライブラリ

このトピックのプロセスでは、手動でOAuthトークンを取得する方法について説明します。このプロセスを支援するために、eBayはアプリケーションでのOAuthトークン発行を迅速に実装するために使用できるいくつかのクライアントライブラリを提供しています（前述のリストを参照）。

アプリケーションアクセストークンの取得と使用の順序

クライアントクレデンシャル付与フローでは、アプリケーションアクセストークンが発行され、その後APIリクエストで使用されます。

リクエストの設定

クライアントクレデンシャル付与リクエストの3つの部分を設定する必要があります。

ターゲットエンドポイントの設定
HTTPリクエストヘッダーの設定
リクエストペイロードの設定

ターゲットエンドポイントの設定

使用するエンドポイントは、ターゲットとする環境によって異なります。

OAuthトークンリクエストエンドポイント

環境	エンドポイント (HTTPメソッド + URL)
Sandbox	`POST https://api.sandbox.ebay.com/identity/v1/oauth2/token`
Production	`POST https://api.ebay.com/identity/v1/oauth2/token`

HTTPリクエストヘッダーの設定

以下のHTTPリクエストヘッダーを設定します。

Content-Type – 次のように設定する必要があります: application/x-www-form-urlencoded
Authorization – "Basic " という単語の後に、Base64エンコードされたOAuthクレデンシャル (<client_id>:<client_secret>) を続けます。

詳細については、「Base64エンコードされたクレデンシャルの生成」のセクションを参照してください。

リクエストペイロードの設定

POST リクエストのペイロードを以下の値でフォーマットします。

grant_type を client_credentials に設定します。
scope を、アクセストークンで呼び出すインターフェースに必要なスコープのURLエンコードされたスペース区切りリストに設定します。

詳細については、「アクセストークン発行時のスコープ指定」のセクションを参照してください。

アプリケーションアクセストークンを使用すると、アプリケーションはeBayの呼び出しを行うための固有の認可を持ちます。

クライアントクレデンシャル付与リクエスト

クライアントクレデンシャル付与は、新しいアプリケーションアクセストークンを発行する単一のリクエストです。トークンを使用して、アクセストークンに設定されたスコープと一致するAPIメソッドへのリクエストを行います。

以下の呼び出し仕様を使用してリクエストを設定します。

  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

  Request body:
    grant_type=client_credentials
    scope=<scopeList>    // a URL-encoded string of space-separated scopes

ヒント: このページの例はSandboxを対象としています。Production環境を対象とする場合は、表示されているエンドポイントを必ず更新してください。

cURLリクエストの例

以下のコマンドは、cURLを使用してクライアントクレデンシャル付与リクエストを設定する方法を示しています。

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic UkVTVFRlc3...wZi1hOGZhLTI4MmY=' \
  -d 'grant_type=client_credentials&scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope %20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fbuy.item.bulk'

アプリケーションアクセストークンを含むレスポンス

クライアントクレデンシャル付与リクエストを発行すると、eBayは以下のレスポンスに示すような、アプリケーションアクセストークンを含むJSONオブジェクトを返します。

{
  "access_token": "v^1.1#i^1#p^1#r^0#I^3#f^0#t^H4s ... wu67e3xAhskz4DAAA",
  "expires_in": 7200,
  "token_type": "Application Access Token"
}

アクセストークンを使用してAPIリクエストを認可するには、Authorization HTTPヘッダーにトークン値を渡します。

上記の例では、expires_in 要素が7,200秒に設定されており、このトークンは生成された時点から2時間有効であることを意味します。トークンの期限切れ後も継続してアクセスするには、新しいトークンを発行する必要があります。

重要: アクセストークンは機密情報として扱う 必要があり、共有したり公に公開したりしてはいけません。最高のパフォーマンスとセキュリティのために、アプリケーションはこのトークンを静的変数に保存し、有効な間は再利用するべきです。

認可コード付与フロー

認可コード付与フロー (Authorization code grant flow) は、OAuthユーザーアクセストークンを作成するために使用されます。

OAuthクライアントライブラリ

このトピックのプロセスでは、手動でOAuthトークンを取得する方法について説明します。

ユーザーアクセストークンの取得と使用の順序

認可コード付与フローを通じてユーザーの新しいアクセストークンを取得するには、2段階のプロセスが必要です。まず、eBayユーザーから代理でAPI呼び出しを行うための同意を得て（「ユーザーの同意取得」を参照）、その後、各ユーザーに対してユーザーアクセストークンを生成します（「認可コードとユーザーアクセストークンの交換」を参照）。

ユーザーの同意取得

このトピックでは、特定のユーザーのユーザーアクセストークンを取得するために必要な最初のステップである ユーザーの同意 (User consent) について説明します。

ユーザーの同意について

eBayアプリケーションがeBayユーザーの代理として行動する場合、アプリケーションはユーザーの機密リソースにアクセスして更新するリクエストを行う前に、ユーザーの同意を得る必要があります。

eBayユーザーの同意を得た後、認可コード付与リクエストを行って新しいユーザーアクセストークンを発行します。このトークンは、アプリケーションがユーザーのeBayアカウントデータにアクセスすることを許可するユーザーの認可を含んでいます。

同意リクエストの設定

リダイレクトURLの2つの部分を設定する必要があります。

ターゲットエンドポイントの設定
HTTPクエリパラメータの設定

ターゲットエンドポイントの設定

eBay SandboxおよびProduction環境は、異なるサーバー上で Grant Application Access ページをホストしています。以下の表は、サポートされているエンドポイントを示しています。

OAuthトークンリクエストエンドポイント

環境	エンドポイント (HTTPメソッド + URL)
Sandbox	`GET https://auth.sandbox.ebay.com/oauth2/authorize`
Production	`GET https://auth.ebay.com/oauth2/authorize`

HTTPクエリパラメータの設定

以下のクエリパラメータを設定して、同意リクエストを構成します。

同意リクエストURLクエリパラメータ

クエリパラメータ	説明
`client_id`	ターゲットとする環境の `client_id` 値。必須
`locale`	ターゲットとするマーケットプレイスに合わせてOAuth同意ページをローカライズするための `locale` パラメータ。例えば、ドイツの場合は `locale=de-DE` と設定します。オプション
`prompt`	必要に応じて、ユーザーを Grant Application Access ページにリダイレクトした際に、既存のユーザーセッションがある場合でも強制的にログインさせることができます。これを行うには、`prompt` クエリパラメータを `login` に設定します。オプション
`redirect_uri`	ターゲットとする環境の `RuName` 値。詳細については、「redirect_uri値の取得」のセクションを参照してください。必須
`response_type`	eBayに認可コード (authorization code) を生成して返させるために、`code` に設定します。必須
`scope`	アプリケーションが使用するリソースへのアクセスを提供するOAuthスコープのリスト。詳細については、「OAuthを使用したeBay APIへのアクセス」のセクションを参照してください。必須
`state`	リクエストとコールバックの間で状態を維持するためにクライアントが使用する不透明な値。認可サーバーは、ユーザーエージェントをクライアントの承諾URLにリダイレクトする際、リクエストで提供されたものと同じ値を返します。`state` 値はオプションですが、OAuth仕様で説明されているように、クロスサイトリクエストフォージェリ (CSRF) を防ぐためにこの値を提供して使用することを推奨します。オプション

同意リクエスト

アプリケーションの Grant Application Access ページ（ユーザーに対して、アプリケーションがユーザーのeBayアカウントリソースにアクセスするために必要な権限を付与するよう求めるカスタムページ）を通じてユーザーの同意を取得します。

アプリケーションから、「同意リクエスト」と呼ばれるHTMLリダイレクトを使用して、ユーザーをアプリケーションの Grant Application Access ページに誘導します。

以下の同意リクエストは、Sandboxを対象としたHTMLリダイレクトです（読みやすくするために改行されています）。

/* URL redirects a user to the application's Grant Application Access page */

GET https://auth.sandbox.ebay.com/oauth2/authorize?
    client_id=<app-client-id-value>&
    locale=<locale-value>&           // optional
    prompt=login                    // optional
    redirect_uri=<app-RuName-value>&
    response_type=code&
    scope=<scopeList>&               // a URL-encoded string of space-separated scopes
    state=<custom-state-value>&      // optional

このHTMLリクエストは、ユーザーをアプリケーションの Grant Application Access ページにリダイレクトします。ページに記載されている条件に同意すると、リダイレクトによりユーザーはアプリケーションに戻され、アプリケーションへのリダイレクトには 認可コード が含まれます。

Grant Application Access には、アプリケーションの制御下にある特定の機密リソースにアクセスおよび変更するために、ユーザーに許可を求めている項目がリストアップされます。Grant Application Access ページに表示される権限のリスト、およびサードパーティが同意しなければならない権限の完全なリストは、権限付与リクエストで提供されたスコープのリストによって決定されます。

アプリがeBay APIにアクセスするために必要な権限のリストは、権限付与リクエストで提供されたスコープのリストによって決定されます。権限付与リクエストに多くのスコープを含めるほど、ユーザーが同意する必要がある権限が増えます。ユーザーが同意しなければならない権限のリストを削減するには、アプリケーションで使用するメソッドへのアクセスに必要なスコープのみを提供し、アプリケーションが使用しないリソースへのアクセスを示すスコープは除外してください。

Grant Application Accessページ

Grant Application Access ページには、アプリケーションに対してアクセス許可を与えるようユーザーに求めている項目に関する情報が表示されます。ページには、ユーザーがクリックして同意を示すことができる Agree and Continue ボタンが含まれています（拒否を示すための Not now ボタンも含まれています）。

Grant Application Access ページには、付与リクエストに関する情報を提供するリンクや、ユーザーをセラーのアプリケーションに戻すリンクがいくつかあります。セラーは、eBay Developer Programアカウントを通じて、このページのリンクやコンテンツの多くを設定します。

同意リクエストのレスポンス

ユーザーが Grant Application Access ページの "I Agree" ボタンをクリックして同意すると、eBayはユーザーをセラーの Accept URL ページ（セラーのRuNameで設定）にリダイレクトします。アプリケーションへのリダイレクトには、ユーザーの同意を示す 認可コード (authorization code) が含まれます。

/* The redirect to your Accept URL page with the appended authorization code and state value */

https://www.example.com/acceptURL.html?
  state=<client_supplied_state_value>&
  code=v%5E1.1% ... NjA%3D&
  expires_in=299

上記の例は、認可コード値が code パラメータでどのように返されるかを示しています。認可コードは単一のユーザーに紐付けられており、このコードをそのユーザーに紐付けられたユーザーアクセストークンと交換します。

同意リクエストで state パラメータを提供した場合、それもリダイレクトURLで返されます。eBayは、クロスサイトリクエストフォージェリ (CSRF) 攻撃をチェックするためにこのパラメータを使用することを強く推奨します。

認可コードについて

認可コード付与から返される認可コードは、アクセストークンを取得するためにのみ使用できる1回限りのトークンです。認可コードを使用してAPIリクエストを行うことはできません。

code 値に加えて、レスポンスURLには、認可コードが有効な秒数を定義する関連の expires_in 値も含まれています。認可コードが期限切れになる前に使用して、ユーザーの代理としてAPIリクエストを行うために使用できるユーザーアクセストークンを取得してください。

詳細については、「認可コードとユーザーアクセストークンの交換」のセクションを参照してください。

認可コードとユーザーアクセストークンの交換

ユーザーがアプリケーションに対して代理で行動する権限を付与すると、eBayは指定されたスコープに対するユーザーの同意を含む 認可コード を返します。この認可コードを、一般に 認可コード付与リクエスト と呼ばれる POST リクエストで使用します。このリクエストは、ユーザーアクセストークンとその関連リフレッシュトークンを取得します。

認可コードの長さは最大1024文字です。この値を保存せず、認可コード付与に直接渡されるランタイムパラメータとしてのみ使用してください。

リクエストの設定

認可コード付与リクエストの3つの部分を設定する必要があります。

ターゲットエンドポイントの設定
HTTPリクエストヘッダーの設定
リクエストペイロードの設定

ターゲットエンドポイントの設定

使用するエンドポイントは、ターゲットとする環境によって異なります。

OAuthトークンリクエストエンドポイント

環境	エンドポイント (HTTPメソッド + URL)
Sandbox	`POST https://api.sandbox.ebay.com/identity/v1/oauth2/token`
Production	`POST https://api.ebay.com/identity/v1/oauth2/token`

HTTPリクエストヘッダーの設定

以下のHTTPリクエストヘッダーを設定します。

Content-Type – 次のように設定する必要があります: application/x-www-form-urlencoded
Authorization – Basic という単語の後に、Base64エンコードされたOAuthクレデンシャル (<client_id>:<client_secret>) を続けます。

詳細については、「Base64エンコードされたクレデンシャルの生成」のセクションを参照してください。

リクエストペイロードの設定

POST リクエストのペイロードを以下の値でフォーマットします。

grant_type を authorization_code に設定します。
redirect_uri を、アプリケーションとターゲット環境に割り当てられた RuName 値に設定します。詳細については、「redirect_uri値の取得」のセクションを参照してください。
code を、ユーザーが同意した際にeBayから返されたURLエンコードされた 認可コード 値に設定します。詳細については、「サードパーティの同意の取得」のセクションを参照してください。

ヒント: eBayによって返される認可コードはURLエンコードされています。この値は、認可コード付与リクエストの code パラメータで渡す際にURLエンコードされている必要があります。ただし、リクエストを行うために使用するメソッドが渡された値を自動的にURLエンコードする場合は、認可コード付与リクエストで使用する前に認可コードをURLデコードする必要があります。

認可コード付与リクエスト

認可コード付与は、新しいユーザーアクセストークンを発行するリクエストです。トークンを使用して、アクセストークンに設定されたスコープと一致するAPIメソッドへのリクエストを行います。

以下の呼び出し仕様を使用してリクエストを設定します。

  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

  Request body:
    grant_type=authorization_code
    code=<authorization-code-value>
    redirect_uri=<RuName-value>

cURLリクエストの例

以下のコマンドは、cURLを使用して認可コード付与リクエストを設定する方法を示しています（読みやすくするために改行されています）。

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \
  -d 'grant_type=authorization_code&
      code=v%5E1.1%23i%5E1%23f% ... 3D%3D&
      redirect_uri=Davy_Developer-DavyDeve-DavysT-euiukxwt'

ユーザーアクセストークンを含むレスポンス

認可コード付与リクエストを発行すると、eBayは以下のようなフィールドを含むJSONオブジェクトを返します。

{
  "access_token": "v^1.1#i^1#p^3#r^1...XzMjRV4xMjg0",
  "expires_in": 7200,
  "refresh_token": "v^1.1#i^1#p^3#r^1...zYjRV4xMjg0",
  "refresh_token_expires_in": 47304000,
  "token_type": "User Access Token"
}

アクセストークンを使用してAPIリクエストを認可してください。

この例はSandbox環境を対象としているため、このアクセストークンはSandboxへのAPI呼び出しにのみ使用できます。Production環境へのリクエストを行うには、eBayに送信する各トークンリクエストにおいて、Production環境の値（OAuthクレデンシャル、RuName、およびURL）を使用してトークン生成プロセスを繰り返してください。

ユーザーアクセストークンについて

新しく発行されたユーザーアクセストークンと共に返される expires_in 値は、そのトークンが有効な秒数を示します。

上記の例では、トークンは生成された時点から7,200秒（2時間）有効です。トークンの期限切れ後は、提供されたリフレッシュトークンを使用して更新する必要があります。

リフレッシュトークン

ユーザーアクセストークンは 短寿命 ですが、関連付けられた refresh_token は 長寿命 の値であり、期限切れになったユーザーアクセストークンを更新するために使用できます。これにより、新しいユーザーアクセストークンが必要になるたびにユーザーの同意を得る必要がなくなります。

トークンの期限切れ後に更新する方法については、「リフレッシュトークンを使用したユーザーアクセストークンの更新」のセクションを参照してください。

リフレッシュトークンを使用したユーザーアクセストークンの更新

新しいユーザーアクセストークンを発行すると、アクセストークンと共に リフレッシュトークン が返され、これを使用して関連するユーザーのユーザーアクセストークンを更新できます。リフレッシュトークンリクエスト は、元のアクセストークンと同じ認可プロパティを含むアクセストークンを発行します。

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

セキュリティのため、ユーザーアクセストークンは短寿命です。しかし、リフレッシュトークンは長寿命であり、トークンの期限切れ後にユーザーアクセストークンを更新するために使用できます。利点として、ユーザーアクセストークンを更新する必要があるたびにアカウント所有者の同意を得る必要がありません。

リフレッシュトークン使用のシーケンス

アプリケーションは、アカウントに関連付けられたアクセストークンが有効である限り、eBayユーザーの代理としてAPI呼び出しを行うことができます。アクセストークンが期限切れになった場合は、以下のロジックを使用してユーザーアクセストークンを更新してください。

リフレッシュトークンを使用したユーザーアクセストークン生成のシーケンス

API呼び出しを行う。
アクセストークンが無効な場合（期限切れ）、リフレッシュトークンリクエストを行う。
新しいアクセストークンを取得する。
API呼び出しを再試行する。

リフレッシュトークンリクエストの設定

リフレッシュトークンリクエストの3つの部分を設定する必要があります。

ターゲットエンドポイントの設定
HTTPリクエストヘッダーの設定
リクエストペイロードの設定

ターゲットエンドポイントの設定

使用するエンドポイントは、ターゲットとする環境によって異なります。

OAuthトークンリクエストエンドポイント

環境	エンドポイント (HTTPメソッド + URL)
Sandbox	`POST https://api.sandbox.ebay.com/identity/v1/oauth2/token`
Production	`POST https://api.ebay.com/identity/v1/oauth2/token`

HTTPリクエストヘッダーの設定

以下のHTTPリクエストヘッダーを設定します。

Content-Type – 次のように設定する必要があります: application/x-www-form-urlencoded
Authorization – Basic という単語の後に、Base64エンコードされたOAuthクレデンシャル (<client_id>:<client_secret>) を続けます。

詳細については、「Base64エンコードされたクレデンシャルの生成」のセクションを参照してください。

リクエストペイロードの設定

POST リクエストのペイロードを以下の値でフォーマットします。

grant_type を refresh_token に設定します。
refresh_token を、認可コード付与リクエストから返されたリフレッシュトークン値に設定します。リフレッシュトークンを取得するには、新しいユーザーアクセストークンを発行する必要があります。このプロセスは「ユーザーの同意の取得」から始まります。
scope を、元の同意リクエストで使用したのと同じURLエンコードされたスコープのリストに設定します。スコープの詳細については、「OAuthを使用したeBay APIへのアクセス」のセクションを参照してください。

注意: scope パラメータはオプションです。scope パラメータを指定しない場合、デフォルトは同意リクエストに含まれていたスコープ値のセットになります。scope パラメータを指定する場合、含まれるスコープ値は同意リクエストに含まれていたスコープ値と等しいか、そのサブセットである必要があります。

リフレッシュトークンリクエスト

リフレッシュトークンリクエストを使用して期限切れのユーザーアクセストークンを更新するには、以下のようにターゲットURL、HTTPヘッダー、およびリクエストペイロードを設定します。

  HTTP method:   POST
  URL (Sandbox): https://api.sandbox.ebay.com/identity/v1/oauth2/token

  HTTP headers:
    Content-Type = application/x-www-form-urlencoded
    Authorization = Basic <B64-encoded-oauth-credentials>

  Request body:
    grant_type=refresh_token
    refresh_token=<your-refresh-token-value>
    scope=<scopeList>    // a URL-encoded string of space-separated scopes

cURLリクエストの例

以下のコマンドは、cURLを使用してリフレッシュトークンリクエストを設定する方法を示しています（コードは読みやすくするために改行されています）。

curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \
  -d 'grant_type=refresh_token&
      refresh_token=v^1.1#i^1#p^3# ... fMSNFXjEyODQ=&
      scope=https://api.ebay.com/oauth/api_scope/sell.account%20https://api.ebay.com/oauth/api_scope/sell.inventory'

更新されたユーザーアクセストークンを含むレスポンス

リフレッシュトークンリクエストを発行すると、eBayは新しいアクセストークンを発行し、以下のようなJSONレスポンスで返します。

{
  "access_token": "v^1.1#i ... AjRV4yNjA=",
  "expires_in": 7200,
  "token_type":"User Access Token"
}

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

アカウントに関連付けられたリフレッシュトークンが有効である限り、特定ユーザーの新しいユーザーアクセストークンを発行するためにリフレッシュトークンを使用し続けることができます。ただし、長寿命のリフレッシュトークンが期限切れになった場合、またはアプリが必要とするスコープを更新した場合は、「サードパーティの同意の取得」から始めて、アクセストークンとリフレッシュトークンの両方を更新する必要があります。

各アクセストークンの寿命を追跡し、期限切れになる前にリフレッシュすることは可能ですが、複数のトークンの寿命を追跡するために必要な処理とストレージは、多くの場合、トークンが期限切れになった後にリフレッシュする処理の負担を上回ります。このため、各トークンを期限切れになる前に更新しようとするよりも、期限切れになってから（"Invalid access token" エラーを受信してから）リフレッシュするのが最適です。

重要: リフレッシュトークンは、eBay上での様々なセラー活動により取り消される場合があります。具体的には、セラーがeBayメンバーログイン名またはeBayアカウントのパスワードを変更した場合、アカウントに関連付けられた有効なリフレッシュトークンはeBayによって自動的に取り消されます。さらに、セラーは自身のeBayアカウントページを通じてトークンを取り消すことを選択できます。

リフレッシュトークンが取り消された場合（または期限切れになった場合）、関連するユーザーの新しいアクセストークンとリフレッシュトークンを取得するために、同意リクエストフローをやり直す必要があります。

Auth'n'Authトークンについて

2つのアプリケーションユースケース、またはモデルがあります。モデルはアプリケーションによってサポートされるユーザーの数によってのみ異なります。

シングルユーザーモデル (Single User Model) では、アプリケーションは単一のユーザーのみをサポートします。このモデルでは、Auth'n'Authトークンは1つだけ必要です。開発者アカウントの User Tokens (eBay Sign-In) ページを使用して、アプリケーションのユーザー用の単一トークンを生成できます。Production環境で作成されたAuth'n'AuthトークンはeBayユーザーIDに関連付けられ、Sandbox環境で作成されたAuth'n'AuthトークンはSandboxテストユーザーに関連付けられます。

ソリューションプロバイダーモデル (Solutions Provider Model) では、アプリケーションは複数のユーザーをサポートします。この場合、アプリケーション内から直接ユーザートークンを取得する機能を実装する必要があります。以下のセクションでは、eBayユーザーのトークンを取得するようにアプリケーションを設定する方法、ユーザーがアプリケーションを利用できるようにするトークンを取得する方法、トークンの使用方法、および期限切れ時の交換方法について説明します。

寿命と一意性

通常、アプリケーションはユーザーサインインと同意プロセスを通じて各ユーザーのユーザートークンを取得し、その後の使用のためにトークンを保存します。ユーザートークンをデータベースに保存する場合、以下の点を知っておく必要があります。

長さは最大2KBで、Base64エンコードされています。
以下の文字を含めることができます: a～z、A～Z、0～9、アスタリスク、スラッシュ、プラス (* / +)

トークンは、アプリケーションの複数のセッションにわたって18ヶ月間有効です。トークンの期限が切れる7日前になると、eBayはそのeBayユーザーの代理としてアプリケーションが行うすべての呼び出しのレスポンス内の HardExpirationWarning 要素フィールドで有効期限を返します。アプリケーションがこのフィールドを検出した場合、この警告にある日付までにユーザーをeBayサイトのサインインページにリダイレクトする必要があります。そうしないと、トークンはそのeBayユーザーを認証する手段として機能しなくなります。

アプリケーションは、トークンの有効期間終了の少なくとも7日前に通知を受けるため、ユーザーの新しいトークンを生成するプロセスを開始できます。通常、古いトークンが実際に期限切れになる前に新しいトークンが生成されます。ただし、特定のアプリケーション/ユーザーの組み合わせに対して新しいトークンを作成すると、以前のトークンは無効になることに注意してください。

eBayは、ユーザーがアプリケーションを再認可する十分な時間を確保できるよう、トークンの有効期限の数ヶ月前にエンドユーザーにメッセージを送ることを推奨します。トークンを作成した日付を追跡し、eBayから別の指示がない限り、18ヶ月間有効であると想定してください。

トークンが期限切れになり、新しいトークンが生成されない場合、アプリケーションはそのユーザー名義でAPI呼び出しを行うことができなくなります。これは、ユーザーのeBayアカウントや、ユーザーが使用している他のアプリケーションには影響しません。新しいトークンが生成されると、アプリケーションは再びそのユーザーの代理として機能呼び出しを行うことができるようになります。

トークンが期限切れになると、そのトークンを使用したすべての呼び出しはエラー932「Auth token is hard expired」で失敗します。予期しないユーザートークンの失敗を避けるため、アプリケーションにはこのエラーを処理するロジックを含める必要があります。

ハード有効期限切れ警告要素 (HardExpirationWarning)

SOAP形式の呼び出しでは、7日間の警告は HardExpirationWarning 要素で返されます。この要素は、7日間の警告期間内に行われたAPI呼び出しへのレスポンスのヘッダーで返されます。

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" 
               xmlns:xs="https://www.w3.org/2001/XMLSchema"
               xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
  <soap:Header>
    <ebl:RequesterCredentials soapenv:mustUnderstand="0">
      <HardExpirationWarning>
      ... DATE OF EXPIRATION HERE ...
      </HardExpirationWarning>
    </ebl:RequesterCredentials>
  </soap:Header>
... Call body ...
</soap:Envelope>

XML 7日間警告レスポンス

<?xml version="1.0" encoding="UTF-8"?>
  <GeteBayOfficialTimeResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <Timestamp>2005-01-12T18:29:48.312Z</Timestamp>
  <Ack>Success</Ack>
  <CorrelationID>00000000-00000000-00000000-00000000-00000000-00000000-0000000000
  </CorrelationID>
  <Version>393</Version>
  <Build>20050110220901</Build>
  <HardExpirationWarning>2005-01-14 03:34:00</HardExpirationWarning>
</GeteBayOfficialTimeResponse>

取り消されたトークン

eBayユーザーは、My eBayのサードパーティアプリのアクセス（Third-party app access）ページに移動してトークンを取り消すことができます。

ユーザーがアプリケーションのトークンを取り消すと、そのトークンは即座に期限切れになります。期限切れのトークンで行われたAPI呼び出しはエラー（エラーコード 16110）で失敗します。

セキュリティ上の懸念によるeBayによるトークンの取り消し

アカウントまたはアプリケーションのセキュリティ侵害の可能性を示す不審なアクティビティをeBayが検出した場合、影響を受けるすべてのユーザートークンは即座に取り消されます。取り消されたトークンで行われたAPI呼び出しは失敗します（エラーコード 17470）。

Auth'n'Authトークンの取得

アプリケーションがユーザーのトークンを取得するプロセスの概要は以下の通りです。

ユーザーがアプリケーションを使用する意思を示します。
アプリケーションはeBayにセッションIDをリクエストし、それを受け取ります。
アプリケーションはセッションIDとアプリケーションの識別子を含むURLを構築し、このURLを使用してユーザーをeBayサインインページに送信します。
ユーザーはeBayにサインインします。
eBayはユーザーにアプリケーションの同意フォームを提示します。
ユーザーは同意します。
アプリケーションがAcceptURLをホストしている場合、eBayはユーザーをそのURLに戻します。
アプリケーションは、リクエスト内でセッションIDによって識別されるユーザーのトークンをリクエストします。
eBayはトークンをアプリケーションに返します。

トークンの取得プロセスは、Web対応アプリケーション（AcceptURLとRejectURLをホストできる）と、クライアントデスクトップアプリケーション（URLをホストしない）とでは少し異なります。

以下のセクションでは、クライアント/デスクトップアプリケーションとWebアプリケーションのプロセスについて説明します。

クライアント/デスクトップアプリケーション

アプリケーションにWebコンポーネントがない場合、またはAcceptURLやRejectURLページをホストしたくない場合は、この方法でトークンを取得してください。

このプロセスでは、一部のステップはユーザーによって、一部はeBayによって、一部はアプリケーションによって完了されます。

ユーザーがアプリケーションを使用する意思を示します（例：アプリケーションインターフェースのSubscribeボタンをクリックするなど）。
アプリケーションはeBayに対して GetSessionID リクエストを行い、セッションID (SessionID) を受け取ります。GetSessionID の詳細はリファレンスを参照してください。アプリケーションはセッションIDを使用して、ユーザーをeBayサインインページおよび同意フォームに送信するeBayサインインURLを構築します。
以下のURLを使用して、ユーザーをeBayサインインページにリダイレクトします。
https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID
URLには &SessID=SessionID と &RUName=RUName を含める必要があります。SessionID はユーザーを識別し、RUName はアプリケーションを識別します。SessionIDはサインインURL内でURLエンコードされている必要があります。
Sandbox用の同等のURLは以下の通りです。
https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID
ユーザーはeBayサインインページでサインインします。
eBayはユーザーをアプリケーションの同意フォームに転送します。
ユーザーはアプリケーションに同意するか、拒否します。
eBayはユーザーをアクションを確認するeBayページに転送します。
アプリケーションは FetchToken を呼び出してユーザートークンを取得します。

Web/サーバーアプリケーション

アプリケーションにWebコンポーネントがあり、開発者アカウントで指定されたURLへのリダイレクトに応答できる場合は、この方法でトークンを取得してください。

このプロセスでは、一部のステップはユーザーによって、一部はeBayによって、一部はアプリケーションによって完了されます。

ユーザーがアプリケーションを使用する意思を示します（例：アプリケーションインターフェースのSubscribeボタンをクリックするなど）。
アプリケーションはeBayに対して GetSessionID リクエストを行います。
アプリケーションはセッションID (SessionID) を受け取ります。
アプリケーションは、ユーザーをeBayサインインページおよび同意フォームに送信するeBayサインインURLを構築します。
Productionトークン用のサインインURL:
https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID
Sandbox用のサインインURL:
https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID
URLにおいて、SessionID はユーザーを識別し、RUName はアプリケーションを識別します。SessionID はサインインURL内でURLエンコードされている必要があります。これは GetSessionID を呼び出して取得したセッションIDです。
Webアプリケーションでは、Submitボタンを含むHTMLフォームを使用してeBayサインインURLを構築できることに注意してください。例：
```
<INPUT TYPE="submit" NAME=AUTHORIZE VALUE="Launch Auth & Auth"
  onclick="window.open('https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=$RUName&SessID=$SessionID');">
```
アプリケーションは、サインインURLに追加のパラメータ ruparams を使用して、ユーザーが同意した後にアプリケーションに渡したいユーザーデータを保持できます。ユーザー同意後、eBayは ruparams 情報をAcceptURLまたはRejectURLページにユーザーを誘導するURLに追加します。このデータはeBayによっては一切使用されません。
ruparams で渡すデータは、それぞれ変数名とURLエンコードされた値の形式で構成される0個以上の情報で構成されます。eBayがアプリケーションのAcceptURLまたはRejectURLにリダイレクトすると、ruparamsの値は名前と値のペアにURLデコードされます。例えば、アプリケーションが以下を送信した場合：
...&ruparams=VarA%3DB12309%26VarB%3DABC123
eBayはURLで以下を返します：
...&VarA=B12309&VarB=ABC123
ユーザーはeBayサインインページでサインインします。
eBayはユーザーをアプリケーションの同意フォームに転送します。
同意フォームで、ユーザーはアプリケーションに同意するか、拒否します。
eBayは同意したユーザーをアプリケーションのAcceptURLに、拒否したユーザーをアプリケーションのRejectURLにリダイレクトします。
サインインURLの ruparams でユーザーデータを渡した場合、eBayはこのデータをAcceptURLまたはRejectURLに追加します。アプリケーションは、拒否したユーザーに対して、アプリケーションがユーザー名義でAPI呼び出しを行うことができない（つまり、ユーザーがアプリケーションを使用できない）ことを示す意味のあるエラーまたはメッセージを表示する必要があります。
アプリケーションは FetchToken を呼び出してユーザートークンを取得します。

「FetchTokenによるトークンの取得」のセクションを参照してください。

一度セットアップが完了すれば、アプリケーションは見込みユーザーに応答し、彼らのトークンを取得できます。

アプリケーションにユーザーが1人しかいない場合は、「開発者ポータル経由でのアクセストークンの取得」で概説されているのと同じプロセスをAuth'n'Authユーザートークンにも使用できます。OAuthとAuth'n'Authのユーザートークンを取得するプロセスは基本的に同じですが、User Tokensページで Auth'n'Auth ラジオボタンを選択する点が異なります。

FetchTokenによるトークンの取得

「クライアント/デスクトップアプリケーション」または「Web/サーバーアプリケーション」で説明されたプロセスが完了したら、デスクトップまたはWebアプリケーションから FetchToken を使用してユーザーのトークンを取得します。

デスクトップの例

Webの例

同意プロセス中にアプリケーションが構築したeBayサインインURLにユーザーがアクセスすると、eBayはユーザートークンを生成し、ユーザーのセッションIDとともに48時間保存します。

アプリケーションがこのプロセスを使用してユーザーのトークンを取得するのが初めての場合は、FetchToken を呼び出す前に5〜10秒待機する必要があります。

このセクションには、FetchToken の使用例が含まれています。

以下のSOAP APIの例は、SOAPヘッダーにリクエスタのクレデンシャルを含む FetchToken 呼び出しを示しています。

SOAPを使用したプログラムによるトークンの取得

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xs="https://www.w3.org/2001/XMLSchema"
xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
  <soap:Header>
    <ebl:RequesterCredentials soapenv:mustUnderstand="0">
     <Credentials>
       <AppId>MyAppID</AppId>
       <DevId>MyDevID</DevId>
       <AuthCert>MyCertID</AuthCert>
     </Credentials>
    </ebl:RequesterCredentials>
  </soap:Header>
  <FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <SessionID>MySessionID</SessionID>
    <Version>1169</Version>
  </FetchTokenRequest>
</soap:Envelope>

リクエストペイロードの Credentials コンテナにアプリケーションキーセットの値を渡す代わりに、HTTPヘッダーを通じてアプリケーションキーセットの値を渡すこともできます。以下のXML APIの例は、HTTPヘッダーにリクエスタのクレデンシャルを含む FetchToken 呼び出しを示しています。

X-EBAY-API-APP-NAME:MyAppID
X-EBAY-API-DEV-NAME:MyDevID
X-EBAY-API-CERT-NAME:MyCertID
X-EBAY-API-CALL-NAME:FetchToken
X-EBAY-API-SITEID:0
Content-Type:text/xml
Request Payload:
<?xml version="1.0" encoding="utf-8"?>
<FetchTokenRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>1169</Version>
   <SessionID>MySessionID</SessionID>
</FetchTokenRequest>

トークンの使用

ユーザートークンを使用してSOAP API呼び出しのリクエスタを認証するには、リクエストのヘッダーにトークンを渡します。以下のSOAP APIの例は、トークンを含むヘッダー要素を太字で示しています。

SOAPリクエスト内のトークン

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xs="https://www.w3.org/2001/XMLSchema"
               xmlns:ebl="urn:ebay:apis:eBLBaseComponents">
  <soap:Header>
    <ebl:RequesterCredentials soapenv:mustUnderstand="0">
      ...
      <eBayAuthToken>
        ... USER TOKEN GOES HERE ...
      </eBayAuthToken>
    </ebl:RequesterCredentials>
  <Version>1169</Version>
  </soap:Header>
... Call body ...
</soap:Envelope>

ユーザートークンを使用してXML API呼び出しのリクエスタを認証するには、リクエストXML内の eBayAuthToken 要素にトークンを渡します。以下のXML APIの例は、GeteBayOfficialTime 呼び出しの完全なXMLを示しています。

XMLリクエスト内のトークン

<?xml version="1.0" encoding="utf-8"?>
<GeteBayOfficialTimeRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
    <eBayAuthToken> Token goes here </eBayAuthToken>
  </RequesterCredentials>
</GeteBayOfficialTimeRequest>

eBayの従来のAPIでのOAuthの使用

Trading APIやPost Order APIを含むいくつかのeBayの従来のAPIへのリクエストに、OAuthアクセストークンを使用できます。

APIリクエストの認可

eBay RESTful APIが導入される前は、従来のAPIへのすべてのリクエストは、Auth'n'Auth（authentication and authorization の略）と呼ばれるシステムを使用してリクエストを認可する必要がありました。

新しいeBay RESTful APIを使用し始めると、APIは認可にOAuth アクセストークン の使用を要求することに気づくでしょう。複数のeBay APIを使用したい場合、2つの別々の認可メカニズムを使用する必要があるように見えるため、混乱を招く可能性があります。

OAuthへの標準化

幸いなことに、一部の従来のAPIを認可メカニズムとしてOAuthをサポートするように改良しています。このアップグレードにより、以下の従来のAPIへのリクエストを認可するためにOAuthトークンを使用できるようになりました。

Trading API
Post Order API
Business Policy Management API

上記のすべてのAPIは、「認可コード付与フロー」で作成されたユーザーアクセストークンを必要とします。このセクションの後半で、これらの各APIにOAuthトークンを渡す方法について説明します。

Auth'n'Authと同様に、OAuth認可コード付与フローには ユーザーの同意 による委任が含まれます。これにより、アプリケーションはユーザーを Grant Application Access Page にリダイレクトし、eBayの利用規約に同意してもらう必要があります。そして現在、一部の従来のAPIが認可にOAuthをサポートしているため、ユーザーの同意を一度だけ取得すれば、その後はそのeBayユーザーに対してOAuthをサポートする任意のAPIを呼び出すことができます。

OAuthスコープと従来のAPI

従来のAPIはOAuthスコープを使用しません。

Auth'n'Authの代わりにOAuthを実装する

このセクションでは、サポートされている従来のAPIでAuth'n'Authの代わりにOAuthを使用する方法について詳しく説明します。

Trading APIリクエストでのOAuthの使用

OAuthを使用してTrading APIリクエストを行う手順は以下の通りです。

リクエストペイロードから <RequesterCredentials> フィールドとその関連値を削除します（このフィールドはAuth'n'Authクレデンシャルを渡すために使用されます）。
リクエストに X-EBAY-API-IAF-TOKEN HTTPリクエストヘッダーを追加し、その値に有効なユーザーアクセストークンを入力します。

以下は、GetCategories リクエストに必要なHTTPリクエストヘッダーと関連ペイロードの例です。

HTTP Headers
    X-EBAY-API-IAF-TOKEN              <UserAccessTokenValue>
    X-EBAY-API-CALL-NAME              GetCategories
    X-EBAY-API-SITEID                 0
    X-EBAY-API-COMPATIBILITY-LEVEL    1085

Request Payload
    <?xml version="1.0" encoding="utf-8"?>
    <GetCategoriesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
      <CategorySiteID>0</CategorySiteID>
      <DetailLevel>ReturnAll</DetailLevel>
      <LevelLimit>1</LevelLimit>
    </GetCategoriesRequest>

SOAPリクエストの例

POST https://api.sandbox.ebay.com/wsapi?callname=GetUser&version=1085&siteid=0 HTTP/1.1
Content-Type: text/xml;charset=UTF-8

X-EBAY-API-IAF-TOKEN: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s
Host: api.sandbox.ebay.com

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:urn="urn:ebay:apis:eBLBaseComponents">
  <soapenv:Body>
    <urn:GetUserRequest>
      <urn:Version>1209</urn:Version>
      <urn:MessageID>Soap call - OAuth Token in trading</urn:MessageID>
      <urn:DetailLevel>ReturnAll</urn:DetailLevel>
    </urn:GetUserRequest>
  </soapenv:Body>
</soapenv:Envelope>

非SOAPのXMLリクエストの例

POST https://api.sandbox.ebay.com/ws/api.dll HTTP/1.1
Content-Type: text/xml;charset=UTF-8

X-EBAY-API-COMPATIBILITY-LEVEL : 1209
X-EBAY-API-IAF-TOKEN: v^1.1#i^1#I^3#p^3#f^...r^0#t^H4s
X-EBAY-API-SITEID : 0
X-EBAY-API-CALL-NAME : GetUser
Host: api.ebay.com
<?xml version="1.0" encoding="utf-8"?> 
<GetUserRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Version>1209</Version>
  <MessageID>XML call: OAuth Token in trading</MessageID>
  <DetailLevel>ReturnAll</DetailLevel>
</GetUserRequest>

注意: プラットフォーム通知呼び出し GetNotificationPreferences および SetNotificationPreferences は上記のようにOAuthで動作しますが、プラットフォーム通知を受信するにはアプリケーションをホワイトリストに登録する必要があります。アプリケーションのホワイトリスト登録の詳細については、Developer Technical Supportにお問い合わせください。

Post Order APIリクエストでのOAuthの使用

Post Order APIは、Authorization HTTPリクエストヘッダーを使用してRESTリクエストでOAuthトークンを渡します。Authorizationヘッダーの使用に関する詳細については、「Post-Order API – Making a Call」のドキュメントを参照してください。

OAuthを使用してPost Order APIリクエストを行う手順は以下の通りです。

Authorization HTTPヘッダーの値に、"IAF "（スペース付き）とそれに続く有効なユーザーアクセストークンを入力します。
例:
Authorization : IAF v^1.1...90nH9ZfwTJRzOfW4QAAA=

Business Policy Management APIリクエストでのOAuthの使用

OAuthを使用してBusiness Policy Management APIリクエストを行う手順は以下の通りです。

リクエストからHTTPヘッダー X-EBAY-SOA-SECURITY-TOKEN とその関連するAuth'n'Authトークン値を削除します。
HTTPヘッダー X-EBAY-SOA-SECURITY-IAFTOKEN を追加し、その値に有効なユーザーアクセストークンを入力します。
以下はHTTPヘッダーの一部です：
X-EBAY-SOA-SECURITY-IAFTOKEN : v^1.1...90nH9ZfwTJRzOfW4QAAA=