用户身份校验

PaaS 平台提供了针对当前贝锐产品的交互能力，调用这一类服务时必须在请求中附带被操作用户的身份授权。本文描述平台 HTTP API 的身份验证机制以及调用规范。

基本概念

访问令牌

访问令牌 （AccessToken）是直接代表用户请求信息的凭证。访问令牌是一个 JWT格式的字符串，详细信息参见RFC 7519。

其中用户需要关注 Claims 中的 exp（Expires），该字段是一个 UnixTimestamp，其标识了访问令牌的过期时间，请求发起前调用者需要知道 AccessToken 是否过期，若过期了需要进行刷新。

使用过期或无效的访问令牌请求业务接口，将返回未授权或授权无效（HTTP 401），若用户在贝锐平台修改其安全验证信息，包括但不限于：密码、绑定的手机、邮箱、微信等

刷新令牌

刷新令牌（RefreshToken），一般 AccessToken 的有效时间都较短，AccessToken 过期后调用者可以通过 RefreshToken 进行续约操作，避免需要再次使用用户的实际授权信息或操作（账号密码等）。

刷新令牌一般时效性较长，但它是一次性的，并且与特定的 AccessToken 成对使用。

调用请求

在需要身份验证的接口中，在 HTTP 验证头中附带 AccessToken，例：

POST /my/api HTTP/1.1
Host: my.api.domain.oray.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6F0Ijox...
Content-Type: application/json

客户端实现

1. 客户端获取用户身份授权后保存授权数据（AccessToken、RefreshToken）
2. 客户端（调用方）每次发起业务 API 的请求（需要授权的）检查 AccessToken 的过期时间（可以预留一定的时差阈值）
3. 未过期直接发起请求即可，若过期后通过 续租授权 接口，获取新的授权
4. 续租授权 成功返回新的授权后，替换本地保存的授权信息，并使用新的 AccessToken 发起请求
5. 刷新 API 返回 401，表示用户身份授权已失效，需要用户重新进行身份授权（登录）操作

相关 API

获取用户授权以及令牌刷新（续约）的 API 可参见：用户身份授权API