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