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:

Create an Application

When you create 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.

 

OAuth Sequence

 

 

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:

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:

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 '/').

 

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://client-app-redirect-uri/

 

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=6513183215H5465sdlkjKils&scope=&state=null

 

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 this set of required parameters:

Parameter Description
code The authorization code returned from the initial request 
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 '/').
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of 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=6513183215-5465sdlkj/ils&
                    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:

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:

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 '/').

 

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://client-app-redirect-uri/

 

 

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=6513183215H5465sdlkjKils&scope=&state=null

 

 

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 this set of required parameters:

Field Description
code The authorization code returned from the initial request.
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 '/').
grant_type As defined in the OAuth 2.0 specification, this field must contain a value of 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=6513183215-5465sdlkj/ils&
                    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