Documentation

 開発者

Digi-KeyのAPIソリューションをご利用いただくには、クライアントアプリケーションのご登録が必要です。 クライアントアプリケーションを登録するには、https://developer.digikey.comからDigi-KeyのAPIソリューションのアカウントを作成してください。 

アカウント作成後、開発者ポータルにログインします。ログインに成功すると、ナビゲーションバーに開発者の名前が表示されます。

開発者の名前をクリックしてドロップダウンメニューを開くと、Sandboxアプリケーションにアクセスが可能です。

Sandbox環境

Sandboxは、APIを使用してクライアントアプリケーションをテストできる安全な環境です。SandboxのAPIは、有効なデータ応答を提供しながらも、実際のリクエストは行いません。SandboxのAPIから返されるデータは完全なものではないかもしれませんが、その構造は本番環境のデータ構造と同じです。Sandboxは、開発者が最初にアクセスする環境です。

Sandboxの目的は、お客様のコードがDigi-KeyのAPI（承認と認証）と通信できるかをテストすることです。 受信した応答は正しいデータ構造を提供しますが、データ自体はリクエストと一致しない場合があります。

当社のAPIと通信可能であることが確認できたら、本番バージョンへの切り替えをお勧めします。

Sandboxアプリケーション

開発者は、Sandboxアプリケーションを作成します。Sandboxアプリケーションは、作成した開発者のみが利用できます。Sandboxアプリケーションは共有できません。

Sandboxアプリケーションの登録

最初に、開発者の名前をクリックしてドロップダウンメニューを開き、アプリケーションを選択します。

「Create Sandbox App」ボタンをクリックして、Sandboxアプリケーションを作成します。

Sandboxアプリケーションのフォームが表示されます。お客様のアプリケーションに関する情報をフォームに入力し、「Add sandbox app」ボタンをクリックしてSandboxアプリケーションを追加します。

Sandboxアプリケーションが作成されました。

Sandboxアプリケーションのプロパティの表示

アプリケーションのプロパティを表示するには、アプリケーション名をクリックします。アプリケーションを編集するには、「Edit」リンクをクリックします。

開発者が定義したアプリケーションのプロパティと、アプリケーションの認証情報が表示されます。

「Edit」タブを選択すると、開発者が定義したアプリケーションのプロパティを編集できます。

アプリケーションの削除

アプリケーションを削除するには、「My Sandbox Apps」ページで「Delete」リンクをクリックします。

または、アプリケーションのプロパティページで「Delete」タブをクリックしても削除できます。

アプリケーションを削除するかの確認メッセージが表示されます。削除する場合は、確認メッセージの下の文字列を入力して、「Delete」ボタンをクリックします。

アプリケーションが削除されました。

2 Legged Authorization

Basic Steps

All client applications, both Sandbox and Production, follow a basic pattern when making requests to a DigiKey API with the OAuth 2.0 framework.

At a high level, there are three steps:

Register an Application

When you register an application, it will be provisioned an OAuth2 client ID and client secret. Copy and secure this information for your client application.

Get an access token

Get an access token by sending the client id, client secret, and grant type to the authorization server’s token endpoint. You will receive an access token.

Send the access token to an API

By passing the access token with a request header, the client application can now make requests to the DK API it is subscribed to. When the access token expires, a new request must be made.

Sandbox Application

Contained below is the necessary information to complete the 2 legged OAuth process for Sandbox Applications. Before continuing, please confirm that a client application is registered, its client id and client secret are stored and secured, and its subscribed to a Sandbox API Product.

Getting the Access Token

The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:

An example of an access token POST request (this is not query parameter):

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& grant_type= client_credentials

A successful response to this request contains the following fields:

A successful response is returned as a JSON object.

Example response to a successful access token request:

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds" 
"expires_in": 599, "token_type": "BearerToken", }

Note: Other fields may be included in the response, and your application should not treat this as an error. The set shown above is the minimum set.

Production Application

Contained below is the necessary information to complete the OAuth process for Production Applications. Before continuing please confirm that a client application is registered, its client id and client secret are stored and secured, and its subscribed to a Production API Product.

Getting the Access Token

The URL used to get your token is:

The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:

An example of an access token POST request (this is not query parameter):

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}& grant_type=client_credentials 

A successful response to this request contains these fields:

A successful response is returned as a JSON object.

Example response to a successful access token request:

{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", 
"expires_in": 599, "token_type": "Bearer", } 

Note: Other fields may be included in the response, and your application should not treat this as an error. The set shown above is the minimum set.

Token Expiration Time

Making an API Call

With OAuth completed the application can send a request.

Developer application example request (Sandbox)

Example request to ProductSearch using developer credentials and endpoint (sandbox-api.digikey.com) :

GET /products/v4/search/P5555-ND/productdetails 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-Customer-Id: 0

Organization application example request (Production)

Example request to ProductSearch using organization credentials and endpoint (api.digikey.com):

GET /products/v4/search/P5555-ND/productdetailsHTTP/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-Customer-Id: 0

The Value of the Authorization header is prefixed with "Bearer"

e.g.: "Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"

The value "Bearer" must be sent with the BearerToken or else you will get a Bearer token error.

"Authorization":"Bearer <BearerToken>"

認証と承認

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