Authentication and Authorization
Overview of OAuth and Digi-Key APIs
The authorization sequence begins when the client application redirects a browser to a Digi-Key URL.
The URL contains query parameters that indicate the type of access being requested.
Digi-Key's Authorization Server handles user authentication and user consent. The end user's My Digi-Key username and password (not the username and password of the developer), is used during the authentication process.
The result is an authorization code, which Digi-Key's Authorization Server returns to your application in a query string.
After receiving the authorization code, the client application can exchange the code (requested with the application's client ID and client secret) for an access token and a refresh token.
The client application can then use the access token to access a Digi-Key API for which it has a subscription.
The refresh token can be used to obtain new access tokens at any time. This is called offline access, because the user does not have to be present when the application obtains a new access token.
Basic Steps
All client applications, both Sandbox and Production, follow a basic pattern when making requests to a Digi-Key API with the OAuth 2.0 framework.
At a high level, there are four 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 authorization code and grant access to application
Get an authorization code by having a user authenticate themselves, by logging into their Digi-Key account. After login the user is asked to authorize the requesting application. Authorization grants the application access to the Digi-Key account. If the user grants permission, Digi-Key's authorization server sends the application an authorization code. If the user does not grant the permission, the authorization server returns an error.
Get an access token
Get an access token by sending the authorization code, client id, client secret, and grant type to the authorization server’s token endpoint. You will receive an access token and a refresh 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, the client application can submit the stored refresh token to receive a new set of credentials.
Sandbox Application
Contained below is the necessary information to complete the 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 Authorization Code
The endpoint for authentication of user, this is done in the browser:
| Sandbox Authorization Endpoint | Description |
| https://sandbox-api.digikey.com/v1/oauth2/authorize | This endpoint is the target of the initial request. It handles authenticating the user and user consent. The result includes the authorization code. |
The set of required query parameters to send url encoded in the browser:
| Parameter | Values | Description |
| response_type | code | Tells the Authorization Server to return an authorization code. |
| client_id | The client id assigned to the registered application. | Identifies the client application making the request. The value passed in this parameter must exactly match the value assigned to it. |
| redirect_uri | Developer defined redirect URI. | Determines where the response is sent. The value of this parameter must exactly match the URI you provided when the application was registered (including trailing '/'). The redirect_uri is provided by the customer. Fill your value in for client-app-redirect-uri. |
| state (optional) | An opaque value used by the client to maintain state between the request and callback. | The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery. |
An example url encoded code request with the required query parameters:
https://sandbox-api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F
Bold in the example above highlights the url encoding of characters. The character ":" is url encoded as "%3A" . The character "/" is url encoded as "%2F"
As seen in browser:
Handling the Response
The response will be sent to the redirect URI as specified in the request URL. If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. All responses are returned to the browser on the query string, as shown below:
An error response:
https://client-app-redirect-uri/code?error=access_denied
An authorization code response:
https://client-app-redirect-uri/?code=lboI52TG&scope=&state=null
Note: The code (ex: lboI52TG) will expire one minute from creation
Getting the Access Token
After the browser receives the authorization code, your application may exchange the authorization code for an access token and a refresh token. The URL used to get your token is:
| Sandbox Access Token Endpoint | Description |
| https://sandbox-api.digikey.com/v1/oauth2/token | This endpoint is the target of the second request. The result of requests to this endpoint includes the access token and refresh token |
The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:
| Parameter | Description |
| code | The authorization code returned from the initial request. The code expires one minute after creation. |
| client_id | This is the client id assigned to the application that you generated within the API Portal. |
| client_secret | This is the client secret assigned to the application that you generated within the API Portal. |
| redirect_uri | Determines where the response is sent. The value of this parameter must exactly match the URI defined when the application was registered (including trailing '/'). The redirect_uri is provided by the customer. Fill your value in for client-app-redirect-uri. |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain the value authorization_code. |
The actual request might look like the following:
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
A successful response to this request contains the following fields:
| Field | Description |
| access_token | The token sent to access a Digi-Key API. |
| refresh_token | A token that can be submitted to obtain a new access token. |
| expires_in | The remaining lifetime of the access token, in seconds. |
| refresh_token_expires_in | The remaining lifetime of the refresh token, in seconds. |
| token_type | The token type being returned. |
A successful response is returned as a JSON object.
Example response to a successful access token request:
{
"access_token": "SLKDosk89/DOSID-frt3234SLsofds",
"refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM",
"expires_in": 1799,
"refresh_token_expires_in": 7775999,
"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.
Using the Refresh Token
As indicated in the previous section, a refresh token is obtained when you get your initial access token. In these cases, your application may obtain a new access token by sending a refresh token to Digi-Key's Authorization Server.
To obtain a new access token this way, your application sends an HTTPS POST request to the token endpoint,
https://sandbox-api.digikey.com/v1/oauth2/token
The request must include this set of required parameters:
| Parameter | Description |
| client_id | The client id assigned to the registered application. |
| client_secret | The client secret assigned to the registered application. |
| refresh_token | The stored refresh token to submit. |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token. |
Such a request will look similar to the following:
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
As long as the user has not revoked the access granted to your application, the response provides a new set of tokens.
Example response to a successful refresh token request:
{
"access_token": "SLKDosk89/DOSID-frt3234SLsofds",
"refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM",
"expires_in": 1799,
"refresh_token_expires_in": 7775999,
"token_type": "BearerToken",
}
Note: The refresh token is regenerated each time you get a new access token. Be sure to save the latest refresh token as older ones will no longer be valid.
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 Authorization Code
The endpoint for authentication of user, this is done in the browser:
| Production Authorization Endpoint | Description |
| https://api.digikey.com/v1/oauth2/authorize | This endpoint is the target of the initial request. It handles authenticating the user and user consent. The result includes the authorization code. |
The set of required query parameters to send url encoded in the browser:
| Parameter | Values | Description |
| response_type | code | Tells the Authorization Server to return an authorization code. |
| client_id | The client id assigned to the registered application. | Identifies the client that is making the request. The value passed in this parameter must exactly match the value assigned by the API Portal. |
| redirect_uri | Developer defined redirect URI | Determines where the response is sent. The value of this parameter must exactly match the URI defined when the application was registered (including trailing '/'). The redirect_uri is provided by the customer. Fill your value in for client-app-redirect-uri. |
| state (optional) | An opaque value used by the client to maintain state between the request and callback. | The authorization server includes this value when redirecting the user-agent back to the client. The parameter SHOULD be used for preventing cross-site request forgery. |
An example url encoded code request with the required query parameters:
https://api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F
Bold in the example above highlights the url encoding of characters. The character ":" is url encoded as "%3A" . The character "/" is url encoded as "%2F"
As seen in browser:
Handling the Response
The response will be sent to the redirect URI as specified in the request URL. If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. All responses are returned to the browser on the query string, as shown below:
An error response:
https://client-app-redirect-uri/code?error=access_denied
An authorization code response:
https://client-app-redirect-uri/code?code=lboI52TG&scope=&state=null
Note: The code (ex: lboI52TG) will expire one minute from creation
Getting the Access Token
After the browser receives the authorization code, your application may exchange the authorization code for an access token and a refresh token. The URL used to get your token is:
| Production Access Token Endpoint | Description |
| https://api.digikey.com/v1/oauth2/token | This endpoint is the target of the second request. The result of requests to this endpoint includes the access token and refresh token |
The request for an access token is an HTTPS POST request and must include the following x-www-form-urlencoded data:
| Field | Description |
| code | The authorization code returned from the initial request. The code expires one minute after creation |
| client_id | The client id assigned to the registered application. |
| client_secret | The client secret assigned to the registered application. |
| redirect_uri | Determines where the response is sent. The value of this parameter must exactly match the URI defined when the application was registered (including trailing '/'). The redirect_uri is provided by the customer. Fill your value in for client-app-redirect-uri. |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain the value authorization_code. |
An example of an authorization code POST request:
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
A successful response to this request contains these fields:
| Field | Description |
| access_token | The token sent to access a Digi-Key API. |
| refresh_token | A token that can be submitted to obtain a new access token. |
| expires_in | The remaining lifetime of the access token, in seconds. |
| refresh_token_expires_in | The remaining lifetime of the refresh token, in seconds. |
| token_type | The token type being returned. |
A successful response is returned as a JSON object.
Example response to a successful access token request:
{
"access_token": "SLKDosk89/DOSID-frt3234SLsofds",
"refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM",
"expires_in": 1799,
"refresh_token_expires_in": 7775999,
"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.
Using the Refresh Token
As indicated in the previous section, a refresh token is obtained when you get your initial access token. In these cases, your application may obtain a new access token by sending a refresh token to Digi-Key's Authorization Server.
To obtain a new access token this way, your application sends an HTTPS POST request to the token endpoint,
https://api.digikey.com/v1/oauth2/token
The request must include this set of required parameters:
| Field | Description |
| client_id | The client id assigned to the registered application. |
| client_secret | The client secret assigned to the registered application. |
| refresh_token | The stored refresh token to submit. |
| grant_type | As defined in the OAuth 2.0 specification, this field must contain a value of refresh_token. |
An example refresh token POST request:
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
As long as the user has not revoked the access granted to your application, the response provides a new set of tokens.
Example response to a successful refresh token request:
{
"access_token": "SLKDosk89/DOSID-frt3234SLsofds",
"refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM",
"expires_in": 1799,
"refresh_token_expires_in": 7775999,
"token_type": "BearerToken",
}
Note: The refresh token is regenerated each time you get a new access token. Be sure to save the latest refresh token as older ones will no longer be valid.
Code and Token Expiration Time
All codes and tokens have an expiration time.
| Type | Expires in |
| Authorization Code | 1 minute |
| Access Token | 30 minutes |
| Refresh Token | 90 days |
Making an API Call
With OAuth completed the application can send a request.
Developer application example request (Sandbox)
Example request to PartSearch using developer credentials and endpoint (sandbox-api.digikey.com) :
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
Organization application example request (Production)
Example request to PartSearch using organization credentials and endpoint (api.digikey.com):
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
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>"