验证与授权
OAuth 和 Digi-Key API 概述
当客户端应用程序将浏览器重定向到 Digi-Key URL 时，授权序列开始。
该 URL 包含指明所请求访问类型的查询参数。
Digi-Key 的授权服务器负责处理用户验证和用户准许。 在验证过程中，使用的是最终用户的“我的 Digi-Key”用户名和密码（而不是开发者的用户名和密码）。
结果返回一个授权码，是由 Digi-Key 的授权服务器以查询字符串的形式返回到您的应用程序的。
客户端应用程序在收到授权码后，可以将该代码（用应用程序的客户端 ID 和客户端密钥进行请求）交换成访问令牌和刷新令牌。
然后，客户端应用程序可以使用访问令牌访问它已订阅的 Digi-Key API。
刷新令牌可用于随时获取新的访问令牌。 这就是所谓的离线访问，因为当应用程序获取新的访问令牌时，用户不必在场。
基本步骤
所有客户端应用程序，同时包括沙盒和生产环境，在使用 OAuth 2.0 框架向 Digi-Key API 发出请求时，都会遵循一基本模式。
总体来说，有四步：
创建应用程序
当您创建应用程序时，将被提供一个 OAuth2 客户端 ID 和客户端密钥。 复制该信息并确保其安全，以备您的客户端应用程序将来使用。
获取授权码并授予应用程序访问权
通过让用户登录自己的 Digi-Key 账户自行进行身份验证，从而获得授权码。 登录后，系统会要求用户对请求的应用程序进行授权。 授权会给应用程序授予对 Digi-Key 账户的访问权。 如果用户授予权限，Digi-Key 的授权服务器就会向应用程序发送一个授权码。 如果用户没有授予权限，授权服务器就会返回一个错误。
获取访问令牌
通过向授权服务器的令牌端点发送授权码、客户端 ID、客户端密钥和授予类型来获取访问令牌。 您将收到一个访问令牌和一个刷新令牌。
将访问令牌发送至 API
通过传递带有请求报头的访问令牌，客户端应用程序现在可以向其订阅的 DK API 发出请求。当访问令牌过期时，客户端应用程序可以提交存储的刷新令牌来接收新一组凭证。
沙盒应用程序
以下是完成用于沙盒应用程序的 OAuth 进程的必要信息。 在继续前，请确认客户端应用程序已经注册，其客户端 ID 和客户端密钥已被存储和保护，并且订阅了沙盒 API 产品。
获取授权码
用于用户验证的端点，这在浏览器中完成：
| 沙盒授权端点 | 描述 |
|---|---|
| https://sandbox-api.digikey.com/v1/oauth2/authorize | 这个端点是初始请求的目标。 它处理用户验证和用户准许。 结果包括授权码。 |
在浏览器中发送 url 编码所需的一组查询参数。
| 参数 | 值 | 描述 |
|---|---|---|
| response_type | 编码 | 告诉授权服务器返回一个授权码。 |
| client_id | 分配给注册应用程序的客户 ID。 | 识别发出请求的客户端应用程序。 此参数中传递的值必须与分配给它的值完全匹配。 |
| redirect_uri | 开发者定义了重定向 URI | 确定响应的发送地点。 这个参数的值必须与您在注册应用程序时提供的 URI 完全匹配（包括后面的 '/'）。 |
url 编码的代码请求和所需的查询参数实例：
https://sandbox-api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2F
在上面的例子中，粗体突出显示了字符的 url 编码。字符 ":" 的 url 编码为 "%3A"。 字符 "/" 的 url 编码为 "%2F"
如浏览器中所见：
处理响应
响应将按照请求 URL 中的指定，发送到重定向 URI。 如果用户批准访问请求，那么响应就会包含一个授权码。 如果用户不批准该请求，则响应会包含一个错误信息。 所有响应都会通过查询字符串返回浏览器，如下所示：
一个错误响应：
https://client-app-redirect-uri/code?error=access_denied
一个授权码响应：
https://client-app-redirect-uri/?code=lboI52TG&scope=&state=null
注意：代码（例如：lboI52TG）在创建后将在一分钟内失效。
获取访问令牌
浏览器收到授权码后，您的应用程序可能会用授权码交换一个访问令牌和一个刷新令牌。 用于获取令牌的 URL 是：
| 沙盒访问令牌端点 | 描述 |
|---|---|
| https://sandbox-api.digikey.com/v1/oauth2/token | 这个端点是第二个请求的目标。 对该端点的请求结果包括访问令牌和刷新令牌 |
访问令牌的请求是一个 HTTPS POST 请求，必须包含以下 x-www-form-urlencoded 数据：
| 参数 | 描述 |
|---|---|
| 编码 | 初始请求返回的授权码。该代码在创建一分钟后失效。 |
| client_id | 这是您在 API 入口中生成的分配给应用程序的客户端 ID。 |
| client_secret | 这是您在 API 入口中生成的分配给应用程序的客户端密钥。 |
| redirect_uri | 确定响应的发送地点。 这个参数的值必须与您在注册应用程序时定义的 URI 完全匹配（包括后面的 '/'）。 |
| grant_type | 按照 OAuth 2.0 规范的定义，这个字段必须包含值 authorization_code。 |
实际请求可能像下面这样：
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
对该请求的成功响应包含以下字段：
| 字段 | 描述 |
|---|---|
| access_token | 为访问 Digi-Key API 而发送的令牌。 |
| refresh_token | 可以为获得新的访问令牌而提交的令牌。 |
| expires_in | 访问令牌的剩余寿命，以秒为单位。 |
| refresh_token_expires_in | 刷新令牌的剩余寿命，以秒为单位。 |
| token_type | 返回的令牌类型。 |
成功响应作为 JSON 对象返回。
成功访问令牌请求的示例响应：
{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }
注意：响应中可能包含其他字段，您的应用程序不应将其视为错误。 上面显示的集合是最小的集合。
使用刷新令牌
如上节所述，当您获得初始访问令牌时，会获得一个刷新令牌。 在这些情况下，您的应用程序可以通过向 Digi-Key 的授权服务器发送刷新令牌来获得新的访问令牌。
为了以这种方式获得新的访问令牌，您的应用程序需要向令牌端点发送一个 HTTPS POST 请求。
https://sandbox-api.digikey.com/v1/oauth2/token
该请求必须包括这组必须的参数：
| 参数 | 描述 |
|---|---|
| client_id | 分配给注册应用程序的客户 ID。 |
| client_secret | 分配给注册应用程序的客户密钥。 |
| refresh_token | 保存下来以备提交的刷新令牌。 |
| grant_type | 按照 OAuth 2.0 规范的定义，这个字段必须包含一个 refresh_token 值。 |
这样的请求看起来会类似下面这个样子：
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
只要用户没有撤销授予您应用程序的访问权，响应就会提供一组新的令牌。
成功刷新令牌请求的示例响应：
{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }
注意：每次获得新的访问令牌时，刷新令牌都会重新生成。 请务必保存最新的刷新令牌，因为旧的令牌将不再有效。
生产应用程序
以下是完成针对生产应用程序的 OAuth 进程必需的信息。 在继续前，请确认客户端应用程序已经注册，其客户端 ID 和客户端密钥已被存储和保护，并且订阅了生产 API 产品。
获取授权码
用于用户验证的端点，这在浏览器中完成：
| 生产授权端点 | 描述 |
|---|---|
| https://api.digikey.com/v1/oauth2/authorize | 这个端点是初始请求的目标。 它处理用户验证和用户准许。 结果包括授权码。 |
在浏览器中发送 url 编码所需的一组查询参数。
| 参数 | 值 | 描述 |
|---|---|---|
| response_type | 编码 | 告诉授权服务器返回一个授权码。 |
| client_id | 分配给注册应用程序的客户 ID。 | 识别发出请求的客户端。 此参数中传递的值必须与 API 入口分配的值完全匹配。 |
| redirect_uri | 开发者定义了重定向 URI | 确定响应的发送地点。 这个参数的值必须与您在注册应用程序时定义的 URI 完全匹配（包括后面的 '/'）。 |
url 编码的代码请求和所需的查询参数实例：
https://api.digikey.com/v1/oauth2/authorize?response_type=code&client_id=123456789abcdefg&redirect_uri=https%3A%2F%2Fclient-app-redirect-uri%2
在上面的例子中，粗体突出显示了字符的 url 编码。字符 ":" 的 url 编码为 "%3A"。 字符 "/" 的 url 编码为 "%2F"
如浏览器中所见：
处理响应
响应将按照请求 URL 中的指定，发送到重定向 URI。 如果用户批准访问请求，那么响应就会包含一个授权码。 如果用户不批准该请求，则响应会包含一个错误信息。 所有响应都会通过查询字符串返回浏览器，如下所示：
一个错误响应：
https://client-app-redirect-uri/code?error=access_denied
一个授权码响应：
https://client-app-redirect-uri/code?code=lboI52TG&scope=&state=null
注意：代码（例如：lboI52TG）在创建后将在一分钟内失效。
获取访问令牌
浏览器收到授权码后，您的应用程序可能会用授权码交换一个访问令牌和一个刷新令牌。 用于获取令牌的 URL 是：
| 生产访问令牌端点 | 描述 |
|---|---|
| https://api.digikey.com/v1/oauth2/token | 这个端点是第二个请求的目标。 对该端点的请求结果包括访问令牌和刷新令牌 |
访问令牌的请求是一个 HTTPS POST 请求，必须包含以下 x-www-form-urlencoded 数据：
| 字段 | 描述 |
|---|---|
| 编码 | 初始请求返回的授权码。 该代码在创建一分钟后失效 |
| client_id | 分配给注册应用程序的客户 ID。 |
| client_secret | 分配给注册应用程序的客户密钥。 |
| redirect_uri | 确定响应的发送地点。 这个参数的值必须与您在注册应用程序时定义的 URI 完全匹配（包括后面的 '/'）。 |
| grant_type | 按照 OAuth 2.0 规范的定义，这个字段必须包含值 authorization_code。 |
一个授权码 POST 请求实例：
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
对该请求的成功响应包含这些字段：
| 字段 | 描述 |
|---|---|
| access_token | 为访问 Digi-Key API 而发送的令牌。 |
| refresh_token | 可以为获得新的访问令牌而提交的令牌。 |
| expires_in | 访问令牌的剩余寿命，以秒为单位。 |
| refresh_token_expires_in | 刷新令牌的剩余寿命，以秒为单位。 |
| token_type | 返回的令牌类型。 |
成功响应作为 JSON 对象返回。
成功访问令牌请求的示例响应：
{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }
注意：响应中可能包含其他字段，您的应用程序不应将其视为错误。 上面显示的集合是最小的集合。
使用刷新令牌
如上节所述，当您获得初始访问令牌时，会获得一个刷新令牌。 在这些情况下，您的应用程序可以通过向 Digi-Key 的授权服务器发送刷新令牌来获得新的访问令牌。
为了以这种方式获得新的访问令牌，您的应用程序需要向令牌端点发送一个 HTTPS POST 请求。
https://api.digikey.com/v1/oauth2/token
该请求必须包括这组必须的参数：
| 字段 | 描述 |
|---|---|
| client_id | 分配给注册应用程序的客户 ID。 |
| client_secret | 分配给注册应用程序的客户密钥。 |
| refresh_token | 保存下来以备提交的刷新令牌。 |
| grant_type | 按照 OAuth 2.0 规范的定义，这个字段必须包含一个 refresh_token 值。 |
一个刷新令牌 POST 请求实例：
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
只要用户没有撤销授予您应用程序的访问权，响应就会提供一组新的令牌。
成功刷新令牌请求的示例响应：
{ "access_token": "SLKDosk89/DOSID-frt3234SLsofds", "refresh_token": "oPu5qu7wPhuVBcTZqmx4NFfhlnSB6hVUJ5uSIhS0CM", "expires_in": 1799, "refresh_token_expires_in": 7775999, "token_type": "BearerToken", }
注意：每次获得新的访问令牌时，刷新令牌都会重新生成。 请务必保存最新的刷新令牌，因为旧的令牌将不再有效。
代码和令牌有效期
所有代码和令牌都有有效期。
| 类型 | 有效期 |
|---|---|
| 授权码 | 1 分钟 |
| 访问令牌 | 30 分钟 |
| 刷新令牌 | 90 天 |
进行 API 调用
OAuth 完成后，应用程序即可发送请求。
开发者应用程序示例请求（沙盒）
使用开发者凭证和端点 (sandbox-api.digikey.com) 向 PartSearch 发出的示例请求：
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
组织应用程序示例请求（生产）
使用组织凭证和端点 (api.digikey.com) 向 PartSearch 发出的示例请求：
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
授权报头的值带有 "Bearer" 前缀
例如："Authorization": "Bearer xGr69sdAjLmnAHwGF4R1HedfDHl3j"
值 "Bearer" 必须和 BearerToken 一起发送，否则会收到一个Bearer 令牌错误。
"Authorization":"Bearer <BearerToken>"