跳转到主要内容
由于应用程序不是将认证请求直接发送给用户，而是将其发送到 Vantage 授权服务器，因此这种认证方案被认为是最安全的。授权服务器随后对用户进行认证，并将授权码返回给客户端。 为了防止授权码被拦截，此认证场景使用了一种名为 PKCE（Proof Key for Code Exchange，代码交换证明密钥）的安全扩展。该扩展的工作方式如下：每个授权请求都需要生成一个加密随机数并将其存储在 code_verifier 中，然后使用该随机数生成一个经过加密签名的值并存储在 code_challenge 中。随后将这个新值发送到授权服务器以获取授权码。 有关 PKCE 的更多信息，请访问此链接。

​
获取授权码

要开始认证流程，将用户重定向到 authorize 端点，并传递以下参数：
ParameterDescription
client_id应用程序标识符。有关如何创建 Vantage API Client（client_id 和 client_secret）的信息，请参阅 “Managing Tenant Vantage API Clients” 一文。
redirect_uri你的应用程序或网站的 URL，用于在授予访问权限后重定向浏览器。
response_type=code指定使用授权码（authorization code）响应类型。
scope=openid permissions global.wildcard指定权限范围（permission scope）。
state任意字符串值，其值会在响应中包含授权结果。
code_challengecode_verifier 代码的数字签名值（使用 code_challenge_method 方法）。
code_challenge_methodcode_verifier 代码的数字签名方法（S256）。
productId=a8548c9b-cb90-4c66-8567-d7372bb9b963Vantage 标识符。
response_type、scope、productId 的取值必须与上方示例完全一致。除 response_type 外，这些键可能会发生变化。建议将它们保存在配置中。
示例请求 在 OAuth 2.0 中，会使用名为 redirect_uri 的参数，其中包含你的资源标识符，以便 Vantage 将授权码发送到你的资源，然后使用该授权码换取访问令牌（access token），而访问令牌是在所有后续 API 调用中进行认证所必需的。使用此认证方法时，需要将 redirect_uri 参数的值提供给 ABBYY 技术支持，以便由管理员将其加入白名单。 一旦使用 scope 参数请求的访问权限被验证并授予，浏览器就会被重定向到由 Vantage 服务器设置的专用网页。该网页包含一个对话窗口，用于使用你的账户完成授权。此页面应在具有可见地址栏的浏览器中打开，以便你验证页面 URL 以及连接的 SSL 证书状态。 如果你的电子邮箱地址关联了不同租户中的多个账户，在你输入电子邮箱地址后，将会被要求选择一个租户并输入密码。你也可以通过以下任一资源直接传递你的租户标识符（tokenId 参数）： 或 系统将要求你输入租户账户的密码。在你输入凭据后，授权会在服务器端完成，应用程序将被授予访问 Vantage API 的权限，你会在请求的响应中收到授权码。 请注意，如果某个站点或应用程序使用此身份验证类型，Vantage 用户将代表其本人，向您添加到允许重定向 URL 列表中的站点或应用程序授予对 Vantage API 的访问权限。为向该站点或应用程序提供访问权限，系统会要求用户使用其登录凭据（用户名和密码）在 Vantage 中进行身份验证。一旦用户通过身份验证，该站点或应用程序将获得以下权限：
  • 以用户身份在 Vantage 租户中管理数据目录，
  • 以用户身份在 Vantage 租户中访问技能，
  • 以用户身份创建和访问 Vantage 事务。
该站点或应用程序将无法更改用户的密码、修改 Vantage 租户中的用户列表或编辑技能。只会授予对 Vantage API 的访问权限。用户一旦授予访问权限，将无法收回该访问权限。

​
获取授权令牌

获取授权码后，您有一分钟时间将其换取访问令牌。向令牌端点发送携带 application/x-www-form-urlencoded 数据的 POST 请求。 请求正文中的参数：
ParameterDescription
code_verifier您生成的校验码。用于确认授权请求的发起。
client_id应用程序标识符。
client_secret安全的应用程序密钥。
code您从服务器获取到的授权码。
redirect_uri在授权步骤中使用的重定向 URL。
grant_type=authorization_code指定使用授权码授权类型。
scope=openid permissions global.wildcard offline_access指定权限范围。要获取刷新令牌，请在 scope 中添加 offline_access。
示例请求： 服务器返回的响应中将包含访问令牌： 
{
  "id_token": "<已隐藏>",
  "access_token": "<已隐藏>",
  "expires_in": 86400,
  "token_type": "Bearer",
  "refresh_token": "<已隐藏>",
  "scope": "openid permissions global.wildcard offline_access legacy.client"
}
有关授权码流程的更多信息，请访问此链接。 对于每种流程，access_token 键包含令牌，而 expires_in 键指明令牌在多长时间后过期（以秒为单位）。默认情况下，访问令牌的有效期为 24 小时（更多信息，请参见 Token lifetimes）。在所有请求中添加以下授权请求头，并将 token 替换为你接收到的值： 
-H "Authorization: Bearer token"
请注意，您可以使用同一账号获取多个令牌。有关授权令牌的更多信息，请访问此链接。

​
获取刷新令牌

如果在配置 Vantage API 客户端时启用了 Allow issuing refresh tokens to refresh access tokens 选项，并且获取访问令牌的请求中包含 scope=openid permissions global.wildcard offline_access 参数，则会在响应中额外收到一个刷新令牌。获取刷新令牌后，可以向令牌端点发送包含以下参数的 POST 请求来刷新访问令牌：
ParameterDescription
client_id应用程序标识符。
client_secret安全的应用程序密钥。
refresh_token从服务器获取的刷新令牌。
grant_type=refresh_token指定使用刷新令牌授权类型。
示例请求：

​
令牌有效期

访问令牌和刷新令牌配置了以下有效期：
  • 访问令牌有效期： 定义已签发的访问令牌允许用户访问 Vantage 的时间段。访问令牌的默认有效期为 24 小时。
  • 刷新令牌有效期： 定义从首次签发访问令牌开始的绝对时间段，在此期间已签发的刷新令牌可用于更新访问令牌。刷新令牌的默认有效期为 30 天。