一、接口说明
本文档详细说明VSaaS服务器如何通过第三方AM系统的API完成令牌交换与用户信息认证，核心包含3个接口：访问令牌获取、令牌刷新、用户信息查询，均基于OAuth 2.0协议实现。在实作本部分前，第三方云平台需向TUTK提供对应的token获取以及用户信息认证的接口以及访问的client_id和client_secret。
二、核心接口详情
（一）获取访问令牌（Get Access Token）
VSaaS服务器向第三方AM系统请求获取Access Token，用于后续用户信息查询。
请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | POST（由第三方提供具体URL，示例：https://vendor-am.com/api/v1/authorize） |
| 请求头（Header） | Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/x-www-form-urlencoded |
请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| grant_type | String | 是 | 固定值："authorization_code" |
| code | String | 是 | APP上报给VSaaS的auth code（授权码） |
响应说明
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| access_token | String | 访问令牌，用于调用用户信息接口 |
| token_type | String | 令牌类型，固定返回："JWT Bearer" |
| expires_in | String | 令牌有效期（单位：秒） |
| refresh_token | String | 刷新令牌，用于Access Token过期后重新获取 |
| scope | String | 令牌权限范围（由第三方AM系统定义） |
响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回Access Token及相关信息 |
| 400 | 参数错误 | 请求参数缺失或格式错误（如grant_type错误、code无效） |
| 401 | 认证失败 | client_id/client_secret无效，或授权码已过期 |
请求体示例（POST方式）
grant_type=authorization_code&code=AUTH_CODE_FROM_THIRD_PARTY
请求示例（curl）
curl --location --request POST 'https://vendor-am.com/api/v1/authorize' \
--header 'Authorization: Basic dXNlcjE6cGFzc3dvcmQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=authorization_code&code=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'
响应示例（成功）
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "JWT Bearer",
"expires_in": "3600",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8...",
"scope": "user.info.read"
}
（二）刷新访问令牌（Get Refresh Token）
当Access Token过期时，VSaaS服务器通过此接口从第三方AM系统获取新的Access Token。
请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | POST（由第三方提供具体URL，示例：https://vendor-am.com/api/v1/authorize） |
| 请求头（Header） | Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/x-www-form-urlencoded |
请求参数
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| grant_type | String | 是 | 固定值："refresh_token"（注：原文档笔误，刷新令牌需指定此类型） |
| refresh_token | String | 是 | 上一次获取Access Token时返回的refresh_token |
响应说明
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| access_token | String | 新的访问令牌 |
| token_type | String | 令牌类型，固定返回："JWT Bearer" |
| expires_in | String | 新令牌有效期（单位：秒） |
| refresh_token | String | 新的刷新令牌（部分系统支持复用旧令牌，以第三方AM定义为准） |
| scope | String | 令牌权限范围（与原Access Token一致） |
响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回新的Access Token及相关信息 |
| 400 | 参数错误 | refresh_token缺失或格式错误 |
| 401 | 认证失败 | refresh_token已过期或无效，需重新获取auth code |
请求体示例（POST方式）
grant_type=refresh_token&refresh_token=REFRESH_TOKEN_FROM_PREVIOUS_RESPONSE
请求示例（curl）
curl --location --request POST 'https://vendor-am.com/api/v1/authorize' \
--header 'Authorization: Basic dXNlcjE6cGFzc3dvcmQ=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'grant_type=refresh_token&refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8...'
响应示例（成功）
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ7...",
"token_type": "JWT Bearer",
"expires_in": "3600",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ6...",
"scope": "user.info.read"
}
（三）获取用户信息（Get User Information）
VSaaS服务器通过此接口从第三方AM系统获取用户核心信息，用于在VSaaS平台创建对应账户。
请求说明
| 项 | 说明 |
|---|---|
| HTTP请求方式 | GET（由第三方提供具体URL，示例：https://vendor-am.com/api/v1/userinfo） |
| 请求头（Header） | Authorization: Bearer {access_token}（使用上述接口获取的Access Token） |
请求参数
无额外请求参数，仅需在Header中携带有效的Access Token。
响应说明
响应参数
| 参数名 | 类型 | 说明 |
|---|---|---|
| String | 用户唯一标识（账户名），VSaaS平台将据此创建对应账户 |
响应状态码
| 状态码 | 徽章 | 说明 |
|---|---|---|
| 200 | 成功 | 请求成功，返回用户email信息 |
| 400 | 参数错误 | 请求格式错误（如Header缺失） |
| 401 | 认证失败 | Access Token无效或已过期 |
请求示例（curl）
curl --location --request GET 'https://3rdpart.am.site/api/v1/userinfo' \
--header 'Authorization: Bearer LKdkjlk8873BNN'
响应示例（成功）
{
"email": "[email protected]"
}
