Overview

The authorization sequence begins when your application redirects a browser to a Digi-Key URL. The URL includes 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, your application can exchange the code (along with a client ID and client secret) for an access token and a refresh token. The application can then use the access token to access a Digi-Key API.

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.

 OAuth Sequence 

Getting your Authentication Code

The URL used when authenticating a user is listed below.

Endpoint Description
https://sso.digikey.com/as/authorization.oauth2 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 query string parameters supported by Digi-Key's Authorization Server are:

Parameter Values Description
response_type code Tells the Authorization Server to return an authorization code.
client_id This is the client id assigned to the application that you generated within the API Portal. 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 This URI must match the redirect URI that you defined while creating your application within the API Portal. Determines where the response is sent. The value of this parameter must exactly match the URI you provided while creating your application within the API Portal (including trailing '/').


An example URL is shown below:

                        https://sso.digikey.com/as/authorization.oauth2?response_type=code&client_id=123456789abcdefg&redirect_uri=https://my-new-app.example.com/code

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://my-new-app.example.com/code?error=access_denied
                    

An authorization code response:

                    https://my-new-app.example.com/code?code=6513183215H5465sdlkjKils
                    

Getting your 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 tokens is listed below.

Endpoint Description
https://sso.digikey.com/as/token.oauth2 This endpoint is the target of the second request. The result of requests to this endpoint includes the access token and refresh token.

This request is an HTTPS POST to the token endpoint and includes the following parameters:

Field Description
code The authorization code returned from the initial request (See above example).
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 This URI must match the redirect URI that you defined while creating your application within the API Portal.
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 /as/token.oauth2 HTTP/1.1
                    Host: sso.digikey.com
                    Content-Type: application/x-www-form-urlencoded

                    code=6513183215-5465sdlkj/ils&
                    client_id={your_client_id}&
                    client_secret={your_client_secret}&
                    redirect_uri=https://my-new-app.example.com/code&
                    grant_type=authorization_code
                    

Note: The client_id and client_secret can be used with basic authorization in the header.

A successful response to this request contains the following fields:

Field Description
access_token The token that can be sent to a Digi-Key API.
refresh_token A token that may be used to obtain a new access token.
token_type This describes the type of token being returned.
expires_in The remaining lifetime of the access token.

A successful response is returned as a JSON object, similar to the following:

                    {
                      "access_token":"weoiaslkjfoiw32/12#kd",
                      "refresh_token":"aslidf390-sdl/jliDLSksli",
                      "token_type": "Bearer",
                      "expires_in":3920
                    }
                    

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 a 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 listed above. The request must include the following parameters:

Field Description
refresh_token The refresh token obtained when you got your last access token.
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.
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 /as/token.oauth2 HTTP/1.1
                    Host: sso.digikey.com
                    Content-Type: application/x-www-form-urlencoded

                    client_id={your_client_id}&
                    client_secret={your_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 includes a new access token. A response from such a request is shown below:

                    {
                      "access_token":"SLKDosk89/DOSID-frt3234SLsofds",
                      "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM",
                      "token_type": "Bearer",
                      "expires_in":3920
                    }
                    

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.