Authentication & Concepts

This page covers the shared concepts required for every DigiKey API integration: OAuth 2.0 authentication, required headers, rate limits, and error handling.

OAuth 2.0

All DigiKey APIs require an OAuth 2.0 bearer token on every request:

Authorization: Bearer <access_token>

There are two supported flows. Which one you need depends on the API.

2-legged flow (Client Credentials)

Use this flow for server-to-server requests where no user is involved. It returns a token that represents your application, not a specific user.

When to use: Product Information v4, Order Status v4, Supply Chain v1, Reference APIs.

Token request:

POST https://api.digikey.com/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Token response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 1800
}

The access token expires in 1800 seconds (30 minutes). Request a new one before it expires.

3-legged flow (Authorization Code)

Use this flow when the API requires access to a specific user's account data. The user must log in to DigiKey and grant permission.

When to use: Quotes v4, Ordering v3, Order Management v1, MyLists v1, Barcode v3, Packing List v1, Product Change Notifications.

Step 1 — Redirect the user to the authorization endpoint:

https://api.digikey.com/v1/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &state=RANDOM_STATE_VALUE

Step 2 — Exchange the authorization code for a token:

POST https://api.digikey.com/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI

Token response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502008a3f..."
}

Step 3 — Refresh the access token:

When the access token expires, use the refresh token to get a new one without requiring user interaction again:

POST https://api.digikey.com/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

The expires_in field in the token response is authoritative. These values may change; always read from the response.

Required headers

Every API request requires these two headers:

Most endpoints that accept a request body also require:

TLS

All connections must use TLS 1.2 or higher. HTTP connections are not accepted.

Rate limits

Rate limits apply per API product subscription.

Rate limit headers are included in every response:

When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

HTTP status codes

DigiKey APIs use standard HTTP status codes.

Standard error response body

{
  "ErrorResponseVersion": "3.0.0.0",
  "StatusCode": 400,
  "ErrorMessage": "Bad Request",
  "ErrorDetails": "The parameter 'Keywords' is required.",
  "RequestId": "fa3e4d88-bfc4-4565-c6d5-a567633c091b",
  "ValidationErrors": [
    {
      "Field": "Keywords",
      "Message": "The Keywords field is required."
    }
  ]
}

Include RequestId in any support requests.

Environments

The sandbox uses the same authentication flow as production. Sandbox product searches return example data rather than live inventory.

Credentials security

• Client ID identifies your application and is safe to include in headers.
• Client Secret must be kept private. Never include it in client-side code or commit it to version control.
• Store secrets in environment variables or a secrets manager.
• Use a development or test application for testing; reserve your production application for production traffic.