認証と承認

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へのリクエスト送信が可能になりました。アクセストークンの有効期間が満了すると、クライアントアプリケーションは、保存しているリフレッシュトークンを送信して、新しい認証情報のセットを受け取ることができます。

 

OAuthシーケンス

 

 

Sandboxアプリケーション

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

 

承認コードを取得

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

Sandbox承認エンドポイント説明
https://sandbox-api.digikey.com/v1/oauth2/authorizeこのエンドポイントは、初期リクエストのターゲットであり、 ユーザーの認証とユーザーの同意を処理します。 結果として、承認コードが返されます。

 

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

パラメータ値説明
response_typeコード承認コードを返すように承認サーバに指示します。
client_id登録済みアプリケーションに割り当てられているクライアントIDリクエストを行っているクライアントアプリケーションを識別します。 このパラメータで渡される値は、割り当てられている値と正確に一致する必要があります。
redirect_uri開発者が設定するリダイレクトURIレスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI（末尾の「/」も含む）と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。
state（オプション）リクエストとコールバックの間で状態を維持するためにクライアントが使用する不透明な値承認サーバは、ユーザーエージェントをクライアントにリダイレクトするときにこの値を追加します。このパラメータは、クロスサイトリクエストの偽造を防止するために使用する必要があります。

 

必要なクエリパラメータによって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は次のとおりです。

Sandboxアクセストークンエンドポイント説明
https://sandbox-api.digikey.com/v1/oauth2/tokenこのエンドポイントは2番目のリクエストのターゲットです。 このエンドポイントへのリクエストの結果には、アクセストークンとリフレッシュトークンが含まれます

 

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

パラメータ説明
コード最初のリクエストに対して返された承認コードです。承認コードは作成後1分で有効期間が満了になります。
client_idこれは、APIポータル内で生成したアプリケーションに割り当てられるクライアントIDです。
client_secretこれは、APIポータル内で生成したアプリケーションに割り当てられるクライアントシークレットです。
redirect_uriレスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI（末尾の「/」も含む）と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。
grant_typeOAuth 2.0の仕様で定義されているように、このフィールドには値authorization_codeを設定する必要があります。

 

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

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

 

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

フィールド説明
access_tokenDigi-Key APIにアクセスするために送信されるトークン
refresh_token新しいアクセストークンを取得するために送信するトークン
expires_inアクセストークンの有効期間の残り（単位：秒）
refresh_token_expires_inリフレッシュトークンの有効期間の残り（単位：秒）
token_type返されるトークンタイプ

 

成功時のレスポンスは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

 

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

パラメータ説明
client_id登録済みアプリケーションに割り当てられているクライアントID
client_secret登録済みアプリケーションに割り当てられているクライアントシークレット
refresh_token送信する保存済みのリフレッシュトークン
grant_typeOAuth 2.0の仕様で定義されているように、このフィールドにはrefresh_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製品を購読していることがあります。

 

承認コードの取得

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

本番承認エンドポイント説明
https://api.digikey.com/v1/oauth2/authorizeこのエンドポイントは、初期リクエストのターゲットであり、 ユーザーの認証とユーザーの同意を処理します。 結果として、承認コードが返されます。

 

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

パラメータ値説明
response_typeコード承認コードを返すように承認サーバに指示します。
client_id登録済みアプリケーションに割り当てられているクライアントIDリクエストを行っているクライアントを識別します。 このパラメータで渡される値は、APIポータルによって割り当てられている値と正確に一致する必要があります。
redirect_uri開発者が設定するリダイレクトURIレスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI（末尾の「/」も含む）と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。
state（オプション）リクエストとコールバックの間で状態を維持するためにクライアントが使用する不透明な値承認サーバは、ユーザーエージェントをクライアントにリダイレクトするときにこの値を追加します。このパラメータは、クロスサイトリクエストの偽造を防止するために使用する必要があります。

 

必要なクエリパラメータによって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://api.digikey.com/v1/oauth2/tokenこのエンドポイントは2番目のリクエストのターゲットです。 このエンドポイントへのリクエストの結果には、アクセストークンとリフレッシュトークンが含まれます

 

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

フィールド説明
コード最初のリクエストに対して返された承認コードです。 承認コードは作成後1分で有効期間が満了になります。
client_id登録済みアプリケーションに割り当てられているクライアントID
client_secret登録済みアプリケーションに割り当てられているクライアントシークレット
redirect_uriレスポンスの送信先を設定します。 このパラメータの値は、アプリケーションの登録時に設定したURI（末尾の「/」も含む）と正確に一致する必要があります。 redirect_uriはユーザーによって設定されます。client-app-redirect-uriに値を入力します。
grant_typeOAuth 2.0の仕様で定義されているように、このフィールドには値authorization_codeを設定する必要があります。

 

承認コード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

 

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

フィールド説明
access_tokenDigi-Key APIにアクセスするために送信されるトークン
refresh_token新しいアクセストークンを取得するために送信するトークン
expires_inアクセストークンの有効期間の残り（単位：秒）
refresh_token_expires_inリフレッシュトークンの有効期間の残り（単位：秒）
token_type返されるトークンタイプ

 

成功時のレスポンスは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

 

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

フィールド説明
client_id登録済みアプリケーションに割り当てられているクライアントID
client_secret登録済みアプリケーションに割り当てられているクライアントシークレット
refresh_token送信する保存済みのリフレッシュトークン
grant_typeOAuth 2.0の仕様で定義されているように、このフィールドにはrefresh_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", }

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

 

 

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

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

タイプ有効期間
承認コード1分
アクセストークン30分
リフレッシュトークン90日

 

 

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 <ベアラートークン>"