OAuth 2.0：クライアントアプリケーション

認証と承認

OAuthとDigi-Key APIの概要

承認シーケンスは、クライアントアプリケーションがブラウザをDigi-Key URLにリダイレクトしたときに開始されます。

そのURLには、リクエストされているアクセスのタイプを示すクエリパラメータが含まれます。

Digi-Keyの承認サーバは、ユーザー認証とユーザーの同意を処理します。 認証プロセス中に使用されるのは、開発者のMyDigiKeyユーザー名＆パスワードでなく、エンドユーザーのユーザー名＆パスワードです。

それらを入力すると、承認コードがDigi-Keyの承認サーバによってクエリ文字列に入れてアプリケーションに返されます。
クライアントアプリケーションは承認コードを受け取った後、そのコード（アプリケーションのクライアントIDとクライアントシークレットを使って要求されたもの）をアクセストークンとリフレッシュトークンと交換できます。

クライアントアプリケーションは、アクセストークンを使用して、購読しているDigi-Key APIにアクセスすることができます。
リフレッシュトークンを使用すれば、いつでも新しいアクセストークンを取得できます。 これは、アプリケーションが新しいアクセストークンをユーザーが直接取得する必要がないため、オフラインアクセスと呼ばれます。

基本的な手順

SandboxとProductionのどちらのクライアントアプリケーションも、OAuth 2.0フレームワークを使用してDigi-Key APIにリクエストを送信する場合は、基本的なパターンに従います。
大まかに言うと、次の4つのステップがあります。

アプリケーションを登録

アプリケーションを登録すると、OAuth2のクライアントIDとクライアントシークレットがアプリケーションに提供されます。 この情報をコピーし、クライアントアプリケーション用に確保します。

承認コードを取得し、アプリケーションへのアクセス権を付与

ユーザーにDigi-Keyアカウントにログインさせて自身で認証を行わせることにより、承認コードを取得します。 ユーザーはログイン後、承認をリクエストしているアプリケーションを承認するように求められます。 承認とは、アプリケーションにDigi-Keyアカウントへのアクセス権を付与することです。 ユーザーがアクセス権を与えると、Digi-Keyの承認サーバがアプリケーションに承認コードを送信します。 ユーザーがアクセス権を与えない場合、承認サーバはエラーを返します。

アクセストークンを取得

承認コード、クライアントID、クライアントシークレット、付与タイプを承認サーバのトークンエンドポイントに送信して、アクセストークンを取得します。 アクセストークンとリフレッシュトークンが送信されます。

アクセストークンをAPIに送信

クライアントアプリケーションは、リクエストヘッダーを使ってアクセストークンを渡すことで、購読しているDK APIへのリクエスト送信が可能になりました。アクセストークンの有効期間が満了すると、クライアントアプリケーションは、保存しているリフレッシュトークンを送信して、新しい認証情報のセットを受け取ることができます。

Sandboxアプリケーション

以下に記載するのは、SandboxアプリケーションのOAuthプロセスを実行するために必要な情報です。 実行に進む前に確認が必要な項目としては、クライアントアプリケーションが登録されていること、クライアントIDとクライアントシークレットが保存・保護されていること、クライアントアプリケーションがSandbox API製品を購読していることがあります。

承認コードを取得

ユーザー認証のエンドポイントはブラウザで行われます。

エンコードされたURLをブラウザで送信するために必要なクエリパラメータのセット：

必要なクエリパラメータによってURLエンコードされたコードリクエストの例：

https://sandbox-api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F

上記の例の太字は、文字のURLエンコードを表しています。文字「：」は「%3A」として、また、 文字「/」は「%2F」として、それぞれURLエンコードされています。

これらは次のようにブラウザでも確認できます。

レスポンスを処理

レスポンスは、リクエストURLで指定したリダイレクトURIに送信されます。 ユーザーがアクセスリクエストを承認すると、承認コードがレスポンスとして出力されます。 承認しない場合は、レスポンスとしてエラーメッセージが出力されます。 以下に示すように、すべてのレスポンスはブラウザのクエリ文字列として出力されます。

エラーとしてのレスポンス：

https://client-app-redirect-uri/code?error=access_denied

承認コードとしてのレスポンス：

https://client-app-redirect-uri/?code=lboI52TG&scope=&state=null

注：承認コード（例：lboI52TG）は作成から1分で有効期間が満了になります。

アクセストークンを取得

ブラウザが承認コードを受け取った後、アプリケーションは承認コードをアクセストークンとリフレッシュトークンと交換することができます。 トークンの取得に使用するURLは次のとおりです。

アクセストークンのリクエストは、HTTPS POSTリクエストであり、以下のx-www-form-urlencodedデータを指定する必要があります。

実際のリクエストの例は次のとおりです。

POST /v1/oauth2/token HTTP/1.1 Host: sandbox-api.digikey.com Content-Type: application/x-www-form-urlencoded code=lboI52TG& client_id=application_client_id& client_secret=application_client_secret& redirect_uri=https://client-app-redirect-uri& grant_type=authorization_code

このリクエストの成功時のレスポンスには、以下のフィールドが含まれます。

成功時のレスポンスはJSONオブジェクトとして返されます。

成功したアクセストークンリクエストへのサンプルレスポンス：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注：レスポンスに他のフィールドが含まれる場合もありますので、アプリケーション内でエラーとして扱わないようにご注意ください。 上記のフィールドは最小の組み合わせです。

リフレッシュトークンを使用

前のセクションで示したように、最初のアクセストークンを取得する場合、リフレッシュトークンが取得されます。 このような場合、アプリケーションは、Digi-Keyの承認サーバにリフレッシュトークンを送信することにより、新しいアクセストークンを取得することができます。

この方法で新しいアクセストークンを取得するため、アプリケーションでHTTPS POSTリクエストをトークンエンドポイントに送信します。

https://sandbox-api.digikey.com/v1/oauth2/token

このリクエストには、以下の必須パラメータのセットを含める必要があります。

そのようなリクエストの例を次に挙げます。

POST /v1/oauth2/token HTTP/1.1 Host: sandbox-api.digikey.com Content-Type: application/x-www-form-urlencoded client_id=application_client_id& client_secret=application_client_secret& refresh_token=123Asfeksodk/jkdsoieDSioIOS-483LidkOOl& grant_type=refresh_token

ユーザーがアプリケーションに付与したアクセス権を取り消していない限り、レスポンスとして新しいトークンセットが出力されます。

成功したリフレッシュトークンリクエストへのサンプルレスポンス：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注：新しいアクセストークンを取得するたびに、リフレッシュトークンが再生成されます。 古いリフレッシュトークンは無効になるため、必ず最新のリフレッシュトークンを保存してください。

本番アプリケーション

以下に記載するのは、本番アプリケーションのOAuthプロセスを実行するために必要な情報です。 実行に進む前に確認が必要な項目としては、クライアントアプリケーションが登録されていること、クライアントIDとクライアントシークレットが保存・保護されていること、クライアントアプリケーションが本番API製品を購読していることがあります。

承認コードの取得

ユーザー認証のエンドポイントはブラウザで行われます。

エンコードされたURLをブラウザで送信するために必要なクエリパラメータのセット：

必要なクエリパラメータによってURLエンコードされたコードリクエストの例：

https://api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F

上記の例の太字は、文字のURLエンコードを表しています。文字「：」は「%3A」として、また、 文字「/」は「%2F」として、それぞれURLエンコードされています。

これらは次のようにブラウザでも確認できます。

レスポンスを処理

レスポンスは、リクエストURLで指定したリダイレクトURIに送信されます。 ユーザーがアクセスリクエストを承認すると、承認コードがレスポンスとして出力されます。 承認しない場合は、レスポンスとしてエラーメッセージが出力されます。 以下に示すように、すべてのレスポンスはブラウザのクエリ文字列として出力されます。

エラーとしてのレスポンス：

https://client-app-redirect-uri/code?error=access_denied

承認コードとしてのレスポンス：

https://client-app-redirect-uri/code?code=lboI52TG&scope=&state=null

注：承認コード（例：lboI52TG）は作成から1分で有効期間が満了になります。

アクセストークンを取得

ブラウザが承認コードを受け取った後、アプリケーションは承認コードをアクセストークンとリフレッシュトークンと交換することができます。 トークンの取得に使用するURLは次のとおりです。

アクセストークンのリクエストは、HTTPS POSTリクエストであり、以下のx-www-form-urlencodedデータを指定する必要があります。

承認コードPOSTリクエストの例：

POST /v1/oauth2/token HTTP/1.1 Host: api.digikey.com Content-Type: application/x-www-form-urlencoded code=lboI52TG& client_id={application_client_id}& client_secret={application_client_secret}& redirect_uri=https://client-app-redirect-uri& grant_type=authorization_code

このリクエストの成功時のレスポンスには、以下のフィールドが含まれます。

成功時のレスポンスはJSONオブジェクトとして返されます。

成功したアクセストークンリクエストへのサンプルレスポンス：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注：レスポンスに他のフィールドが含まれる場合もありますので、アプリケーション内でエラーとして扱わないようにご注意ください。 上記のフィールドは最小の組み合わせです。

リフレッシュトークンを使用

前のセクションで示したように、最初のアクセストークンを取得する場合、リフレッシュトークンが取得されます。 このような場合、アプリケーションは、Digi-Keyの承認サーバにリフレッシュトークンを送信することにより、新しいアクセストークンを取得することができます。

この方法で新しいアクセストークンを取得するため、アプリケーションでHTTPS POSTリクエストをトークンエンドポイントに送信します。

https://api.digikey.com/v1/oauth2/token

このリクエストには、以下の必須パラメータのセットを含める必要があります。

リフレッシュトークンのPOSTリクエストの例：

POST /v1/oauth2/token HTTP/1.1 Host: api.digikey.com Content-Type: application/x-www-form-urlencoded client_id={application_client_id}& client_secret={application_client_secret}& refresh_token=123Asfeksodk/jkdsoieDSioIOS-483LidkOOl& grant_type=refresh_token

ユーザーがアプリケーションに付与したアクセス権を取り消していない限り、レスポンスとして新しいトークンセットが出力されます。

成功したリフレッシュトークンリクエストへのサンプルレスポンス：

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }

注：新しいアクセストークンを取得するたびに、リフレッシュトークンが再生成されます。 古いリフレッシュトークンは無効になるため、必ず最新のリフレッシュトークンを保存してください。

コードとトークンの有効期間

すべてのコードとトークンには有効期間があります。

API呼び出しを行う

OAuthが完了すると、アプリケーションによるリクエスト送信が可能になります。

開発者Sandboxアプリケーションのリクエスト例

開発者の認証情報とエンドポイント（sandbox-api.digikey.com）を使用したPartSearchへのリクエスト例：

GET /Search/v3/Products/p5555-nd HTTP/1.1 Host: sandbox-api.digikey.com X-DIGIKEY-Client-Id: WugAd2A6Lxy3Eu3Mgvov45KUNoguMoUl Authorization: Bearer StgGLw9b3hkwqlWAGBmdYoBNEokm X-DIGIKEY-Locale-Site: US X-DIGIKEY-Locale-Language: en X-DIGIKEY-Locale-Currency: USD X-DIGIKEY-Locale-ShipToCountry: us X-DIGIKEY-Customer-Id: 0

開発者本番アプリケーションのリクエスト例

組織の認証情報とエンドポイント（api.digikey.com）を使用したPartSearchへのリクエスト例：

GET /Search/v3/Products/p5555-nd HTTP/1.1 Host: api.digikey.com X-DIGIKEY-Client-Id: heWGx9w6DK8kZf3jRv5E9jUAhXrGBU67 Authorization: Bearer s4T5DbmFZadjNRAEbUnN9zkU3DBj X-DIGIKEY-Locale-Site: US X-DIGIKEY-Locale-Language: en X-DIGIKEY-Locale-Currency: USD X-DIGIKEY-Locale-ShipToCountry: us X-DIGIKEY-Customer-Id: 0

Authorizationヘッダーの値の前には「Bearer」が付きます。

例："Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"

値「Bearer」はBearerTokenと一緒に送信する必要があります。そうしない場合は、ベアラートークンエラーが発生します。

"Authorization":"Bearer <ベアラートークン>"