OAuth - Authentication and Authorization

Check that your Authorization header is as described in section 2.1 of RFC 6750,  The OAuth 2.0 Authorization Framework: Bearer Token Usage.

 

     GET /resource HTTP/1.1
     Host: server.example.com
     Authorization: Bearer mF_9.B5f-4.1JqM

Authorization Code = 1 min

Access Token = 30 Minutes

Refresh Token = 90 days

 

Authorization Code - granted after authorizing client application with Digikey.com login credentials, used to receive an access token.

Access Token - used to make requests

Refresh Token - used when Access Token is expired. Submit refresh token to receive valid Access Token.

During the authorization process a password form is presented. In this form you will use the credentials for your My DigiKey account.

If you do not have a My DigiKey account it can be created here: https://www.digikey.com/MyDigiKey/Register

If you do not know your My Dig-Key account credentials or username, they can be reset or found here: https://www.digikey.com/MyDigiKey/login

The Refresh Token expires in 90 Days, unless:

  • It is exchanged for a new Access Token (and a new refresh token).
  • The registered application's client id or client secret is reset, all tokens will become invalidated.

Please visit DigiKey's GitHub page for a C# / Java Client Library with OAuth2 here DigiKey GitHub Repository.

If you do not have the infrastructure setup to handle responses from DigiKey, you can use the initial value of https://localhost

 

DigiKey has found that the implementation of OAuth 2.0 is the simplest way to mutually be assured of a user's identity, as well as the user's permitted access to our APIs. For the reason that sensitive information is exposed by our APIs, DigiKey will only allow clients authenticated via OAuth 2.0 access. 

How do I get an access token so my application can call your API's?

When invoking an API from your application, you will need to pass along an access token. The access token can be obtained by making API calls to DigiKey's Authorization Server.  Please see our OAuth 2.0 documentation for more details.

The Client ID is registered to your client application and is needed to access the APIs.

A Customer ID is registered to your My DigiKey account. A Customer ID can be passed into an API request when your account has more than one Customer ID registered.

You may have more than Customer ID if your My DigiKey account uses different currencies or has multiple users registered to it.

 

Error Message:

{'ValidationErrors': [], 'ErrorDetails': 'Ensure the Authorization header has a valid Bearer token', 'ErrorResponseVersion': '3.0.0.0', 'StatusCode': 401, 'RequestId': '98cc4acc-2335-4121-9aba-ddc65fe2be40', 'ErrorMessage': 'The Bearer token is invalid'}

 

Verify the value of the Authorization header is prefixed with "Bearer"

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

 

The word "Bearer" must be sent or else you will get a Bearer token error.

"Authorization":"Bearer <bearertoken>"

API Response - Unexpected Response and Error Codes

To match the API pricing response against the DigiKey website:

  1. Use the Product Details operation of PartSearch API
  2. Validate the request is providing the correct locale information (as set on the website)
  3. Validate the request is providing the same Customer ID in the API request  (as signed in with on the DigiKey website)

This is the only process that will give the exact pricing for a part.

Make request to:

/Search/v3/Products/p5555-nd

Update the API request with locale information:

	--header 'x-digikey-locale-currency: REPLACE_THIS_VALUE' 
	--header 'x-digikey-locale-language: REPLACE_THIS_VALUE' 
	--header 'x-digikey-locale-shiptocountry: REPLACE_THIS_VALUE' 
	--header 'x-digikey-locale-site: REPLACE_THIS_VALUE'

When using the developer portal testing tool, you will receive a 400 error when all required fields for the header are not entered, or a malformed message.

Most likely this is do to the version of the TLS protocol being used. Please make sure your application is using TLSv1.2.

Every API response is accompanied by the following set of headers to identify the status of the client application's consumption.

 

HeaderDescription
X-RateLimit-LimitThe maximum number of requests that the consumer is permitted to make per day.
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.

 

Once an application exceeds the rate limit window, the application will receive a status code of:

429 Too Many Requests

 

When the burst limit is exceeded the response headers change to:

HeaderDescription
Retry-AfterThe seconds until you can retry the request
X-BurstLimit-LimitThe maximum number of requests allowed for the API, number per minute
X-BurstLimit-RemainingThe number of requests remaining in the current rate limit window.
X-BurstLimit-ResetThe seconds until the burst limit window resets
X-BurstLimit-ResetTimeThe time when the burst limit window resets, GMT

 

and a JSON response message like:

{
    "ErrorResponseVersion": "3.0.0.0",
    "StatusCode": 429,
    "ErrorMessage": "BurstLimit exceeded",
    "ErrorDetails": "Please try again after the number of seconds in the Retry-After header",
    "RequestId": "fa3e4d88-bfc4-4565-c6d5-a567633c091b",
    "ValidationErrors": []
}

 

When the daily limit is exceeded the response headers change to:

HeaderDescription
Retry-AfterThe seconds until you can retry the request
X-RateLimit-LimitThe maximum number of requests allowed for the API
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.
X-RateLimit-ResetThe seconds until the exceeded rate limit window resets
X-RateLimit-ResetTimeThe time when the rate limit window resets, GMT

 

and a JSON response message like:

{
    "ErrorResponseVersion": "3.0.0.0",
    "StatusCode": 429,
    "ErrorMessage": "Daily Ratelimit exceeded",
    "ErrorDetails": "Please try again after the number of seconds in the Retry-After header",
    "RequestId": "f4a0c1ab-8b47-4a72-e010-8ebe5d78f96c",
    "ValidationErrors": []
}

 

HTTP Status CodeDescription
200 OKSuccessful.
400 Bad RequestBad input parameter. Error message should indicate which one and why. Somehow your client request is malformed/invalid. Also possible, but less likely, the requested part has not been found.
401 UnauthorizedThe client passed in the invalid access token. Client should refresh the token and then try again. Or you have not subscribed the client application to a DK API product.
404 Not FoundResource not found.
405 Method Not AllowedThe resource doesn't support the specified HTTP verb. You are making a request in a format that is not expected. Example is making a GET request when the data needs to be presented as POST.
429 Too Many RequestsToo many request for rate limiting. Too many requests in a given period of time (>120 per minute), or more than allowed during the current rate limit window.
500 Internal Server ErrorServers are not working as expected. The request is probably valid but needs to be requested again later.
503 Service UnavailableService Unavailable.
Products, Plans, and APIs

The API only accepts what is referenced in the API's documentation.

No, only one part number can be submitted. The API only accepts what is referenced in the API's documentation.

Every API response is accompanied by the following set of response headers to identify the status of your client application's consumption.

 

HeaderDescription
X-RateLimit-LimitThe maximum number of requests that the consumer is permitted to make per day.
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.

Apps can call the sandbox API endpoints but cannot call production. These apps are only visible to you. Production Apps are shared by everyone in your organization and can only call production.

Yes. You can use the "Includes" header in all APIs to list which fields you would like returned.

Keyword search data is cached and may be up to 24 hours stale. Please use ProductDetails for real time pricing and availability.

You can narrow down keyword searches by using the ParametricFilters and values from a previous broader search.

Search Question

If the PartNumber contains special characters, the special characters should be sent URL encoded.

For example, the PartNumber "MCP2221A-I/ML-ND" would be sent URL encoded as "MCP2221A-I%2FML-ND".

The purpose of the sandbox is to test your code’s ability to communicate with our APIs (authorization and authentication).

The data that you receive will have the correct response structure but the data itself may not match your request.

When you have confirmed your ability to communicate with our APIs we recommend that you switch to the production versions.