OAuth - Authentication and Authorization

I'm getting 401 errors with message: "The Bearer token is invalid", what am I doing wrong?

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

What are the expiration times of the OAuth codes and tokens?

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.

Error during "Getting your Authorization Code" process

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

If you do not have a My Digi-Key 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

When does the Refresh Token expire?

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.

Can you provide some pseudo code for OAuth 2.0 implementation of client access to Digi-Key API?

Please visit Digi-Key Electronics' GitHub page for a C# / Java Client Library with OAuth2 here Digi-Key GitHub Repository.

I am trying to create a client application, but I do not have an OAuth redirect URI - what do I do?

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

 

Do I need to use OAuth? May I have a permanent token instead?

Digi-Key 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, Digi-Key will only allow clients authenticated via OAuth 2.0 access. Dig-Key strictly uses the three-legged OAuth flow.

Digi-Key will not permit access via permanent access tokens nor via any other equally less secure processes.

How do I obtain an access token?

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 Digi-Key's Authorization Server.  Please see our OAuth 2.0 documentation for more details.

What is the difference between a Client ID and a Customer ID?

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

A Customer ID is registered to your My Digi-Key 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 Digi-Key account uses different currencies or has multiple users registered to it.

 

Products, Plans, and APIs

Is it possible to POST a unique ID value and have the API return that ID in the response?

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

Can I submit more than one part number for a search?

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

How do I see my API usage?

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.

What is the difference between an App and Organization's Production App?

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.

 

Is there a way to call Product Details or another API to just get pricing without other information?

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

Why is the pricing and quantity available in KeywordSearch different than result from the website or ProductDetails??

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

How can I search for products that have specific attributes such as resistance or size?

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

API Response - Unexpected Response and Error Codes

Pricing response is different than what is on Digi-Key website?

To match the API pricing response against the Digi-Key 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 Digi-Key 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 testing tool in the developer portal, I'm receiving a 400 error - How do I fix this?

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.

 

My client application received a socket exception/connection reset message, what's wrong?

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

I received an error code 429, when can I make a request again?

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": []
}

 

I received an error code (400,401,405,429) what does it mean?

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.

Search Questions

How do I search for parts that contain special characters?

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".