Digi-Key API Products have shared principles, they include:

 

OAuth

Digi-Key APIs implement the OAuth 2.0 authorization framework. The Oauth2 framework is the industry standard way to give third-party applications secure delegated access to protected resources. Every request made to a DK API will require an access token.
The expectation is you will be familiar with OAuth 2.0 and its utilization of the authorization code grant flow, authorization endpoints, token endpoints, redirection endpoints, bearer tokens, and refresh tokens. The authorization code grant flow is the only permitted way of accessing DK APIs.

 

TLS

To protect both parties’ resources, all HTTP traffic is secured using the TLSv1.2 encryption protocol. Client applications will be developed to use TLSv1.2. When accessing DK resources, please validate the endpoint and that it uses TLS.
 

Access Control

To protect both parties’ resources it is important to keep the client application’s Client ID and Client Secret private and secured. Third-party applications are assigned a Client ID and Client Secret. Both the Client ID and Client Secret are unique to the third-party application. They should be secured and should never be made public.

 

Rate Limits

DK APIs have access rate limits. Rate limits are applied at an application level. An application can make 120 requests per minute and 1,000 requests per day. 

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

 

Header	Description
X-RateLimit-Limit	The maximum number of requests that the consumer is permitted to make per day.
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.

 

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

429 Too Many Requests

 

If the burst limit window is exceeded, the response headers will show:

Header	Description
Retry-After	The seconds until you can retry the request
X-BurstLimit-Limit	The maximum number of requests allowed for the API, number per minute
X-BurstLimit-Remaining	The number of requests remaining in the current rate limit window.
X-BurstLimit-Reset	The seconds until the burst limit window resets
X-BurstLimit-ResetTime	The time when the burst limit window resets, GMT

 

and the JSON response message will be 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": []
}

 

If the daily limit window is exceeded the response headers will show:

Header	Description
Retry-After	The seconds until you can retry the request
X-RateLimit-Limit	The maximum number of requests allowed for the API
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The seconds until the exceeded rate limit window resets
X-RateLimit-ResetTime	The time when the rate limit window resets, GMT

 

and the JSON response message will be 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": []
}

 

 

Status Codes

Each API documents the status codes it will send. The response codes returned follow RFC 22616 specifications. Generally the status codes returned are:

HTTP Status Code	Description
200 OK	Successful.
400 Bad Request	Bad 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 Unauthorized	The 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 Found	Resource not found.
405 Method Not Allowed	The 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 Requests	Too 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 Error	Servers are not working as expected. The request is probably valid but needs to be requested again later.
503 Service Unavailable	Service Unavailable.

 

 

Support

For technical concerns about accessing or using DK APIs, visit the support page.