一、接口說(shuō)明
本文檔將說(shuō)明VSaaS服務(wù)器如何通過(guò)第三方AM系統(tǒng)的API完成令牌交換與用戶信息認(rèn)證，核心包含3個(gè)接口：訪問(wèn)令牌獲取、令牌刷新、用戶信息查詢，均基于OAuth 2.0協(xié)議實(shí)現(xiàn)。在實(shí)作本部分前，第三方云平臺(tái)需向TUTK提供對(duì)應(yīng)的token獲取以及用戶信息認(rèn)證的接口以及訪問(wèn)的client_id和client_secret。
二、核心接口詳情
（一）獲取訪問(wèn)令牌（Get Access Token）
VSaaS服務(wù)器向第三方AM系統(tǒng)請(qǐng)求獲取Access Token，用于后續(xù)用戶信息查詢。
1. 請(qǐng)求說(shuō)明
| 項(xiàng) | 說(shuō)明 |
|---|---|
| HTTP請(qǐng)求方式 | POST（由第三方提供具體URL，示例：https://vendor-am.com/api/v1/authorize） |
| 請(qǐng)求頭（Header） | Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/x-www-form-urlencoded |
2. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 說(shuō)明 |
|---|---|---|---|
| grant_type | String | 是 | 固定值："authorization_code" |
| code | String | 是 | APP上報(bào)給VSaaS的auth code（授權(quán)碼） |
3. 響應(yīng)說(shuō)明
3.1 響應(yīng)參數(shù)
| 參數(shù)名 | 類型 | 說(shuō)明 |
|---|---|---|
| access_token | String | 訪問(wèn)令牌，用于調(diào)用用戶信息接口 |
| token_type | String | 令牌類型，固定返回："JWT Bearer" |
| expires_in | String | 令牌有效期（單位：秒） |
| refresh_token | String | 刷新令牌，用于Access Token過(guò)期后重新獲取 |
| scope | String | 令牌權(quán)限范圍（由第三方AM系統(tǒng)定義） |
3.2 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回Access Token及相關(guān)信息 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求參數(shù)缺失或格式錯(cuò)誤（如grant_type錯(cuò)誤、code無(wú)效） |
| 401 | 認(rèn)證失敗 | client_id/client_secret無(wú)效，或授權(quán)碼已過(guò)期 |
4. 接口示例
請(qǐng)求體示例（POST方式）
grant_type=authorization_code&code=AUTH_CODE_FROM_THIRD_PARTY
請(qǐng)求示例（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'
響應(yīng)示例（成功）
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "JWT Bearer",
"expires_in": "3600",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8...",
"scope": "user.info.read"
}
（二）刷新訪問(wèn)令牌（Get Refresh Token）
當(dāng)Access Token過(guò)期時(shí)，VSaaS服務(wù)器通過(guò)此接口從第三方AM系統(tǒng)獲取新的Access Token。
1. 請(qǐng)求說(shuō)明
| 項(xiàng) | 說(shuō)明 |
|---|---|
| HTTP請(qǐng)求方式 | POST（由第三方提供具體URL，示例：https://vendor-am.com/api/v1/authorize） |
| 請(qǐng)求頭（Header） | Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/x-www-form-urlencoded |
2. 請(qǐng)求參數(shù)
| 參數(shù)名 | 類型 | 必選 | 說(shuō)明 |
|---|---|---|---|
| grant_type | String | 是 | 固定值："refresh_token"（注：原文檔筆誤，刷新令牌需指定此類型） |
| refresh_token | String | 是 | 上一次獲取Access Token時(shí)返回的refresh_token |
3. 響應(yīng)說(shuō)明
3.1 響應(yīng)參數(shù)
| 參數(shù)名 | 類型 | 說(shuō)明 |
|---|---|---|
| access_token | String | 新的訪問(wèn)令牌 |
| token_type | String | 令牌類型，固定返回："JWT Bearer" |
| expires_in | String | 新令牌有效期（單位：秒） |
| refresh_token | String | 新的刷新令牌（部分系統(tǒng)支持復(fù)用舊令牌，以第三方AM定義為準(zhǔn)） |
| scope | String | 令牌權(quán)限范圍（與原Access Token一致） |
3.2 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回新的Access Token及相關(guān)信息 |
| 400 | 參數(shù)錯(cuò)誤 | refresh_token缺失或格式錯(cuò)誤 |
| 401 | 認(rèn)證失敗 | refresh_token已過(guò)期或無(wú)效，需重新獲取auth code |
4. 接口示例
請(qǐng)求體示例（POST方式）
grant_type=refresh_token&refresh_token=REFRESH_TOKEN_FROM_PREVIOUS_RESPONSE
請(qǐng)求示例（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...'
響應(yīng)示例（成功）
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ7...",
"token_type": "JWT Bearer",
"expires_in": "3600",
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ6...",
"scope": "user.info.read"
}
（三）獲取用戶信息（Get User Information）
VSaaS服務(wù)器通過(guò)此接口從第三方AM系統(tǒng)獲取用戶核心信息，用于在VSaaS平臺(tái)創(chuàng)建對(duì)應(yīng)賬戶。
1. 請(qǐng)求說(shuō)明
| 項(xiàng) | 說(shuō)明 |
|---|---|
| HTTP請(qǐng)求方式 | GET（由第三方提供具體URL，示例：https://vendor-am.com/api/v1/userinfo） |
| 請(qǐng)求頭（Header） | Authorization: Bearer {access_token}（使用上述接口獲取的Access Token） |
2. 請(qǐng)求參數(shù)
無(wú)額外請(qǐng)求參數(shù)，僅需在Header中攜帶有效的Access Token。
3. 響應(yīng)說(shuō)明
3.1 響應(yīng)參數(shù)
| 參數(shù)名 | 類型 | 說(shuō)明 |
|---|---|---|
| String | 用戶唯一標(biāo)識(shí)（賬戶名），VSaaS平臺(tái)將據(jù)此創(chuàng)建對(duì)應(yīng)賬戶 |
3.2 響應(yīng)狀態(tài)碼
| 狀態(tài)碼 | 徽章 | 說(shuō)明 |
|---|---|---|
| 200 | 成功 | 請(qǐng)求成功，返回用戶email信息 |
| 400 | 參數(shù)錯(cuò)誤 | 請(qǐng)求格式錯(cuò)誤（如Header缺失） |
| 401 | 認(rèn)證失敗 | Access Token無(wú)效或已過(guò)期 |
4. 接口示例
請(qǐng)求示例（curl）
curl --location --request GET 'https://3rdpart.am.site/api/v1/userinfo' \
--header 'Authorization: Bearer LKdkjlk8873BNN'
響應(yīng)示例（成功）
{
"email": "someone@somewhere.com"
}
