🧩 Saas授权接入指南

本指南适用于接入 YOO-AI 平台 API 的第三方开发者，通过 OAuth 2.0 授权码模式 + PKCE 机制获取访问令牌（Access Token），用于安全地访问 YOO-AI 提供的接口。

📘 一、准备工作

接入前，请在韦尼克平台完成以下操作：

注册登录韦尼克平台，完成企业认证
创建一个SaaS应用（智能PPT）

获取APP_id和token，并填入安全域名（对接地址的安全域名，以保证对接的安全性）

🔐 二、授权机制概述（OAuth + PKCE）

PKCE（f Key for Code Exchange）是一种OAuth2.0的安全增强机制。想必传统授权流程，它能防止授权码被中间人拦截。

流程核心逻辑：

客户端生成code_verifier，派生出code_challenge并发起授权请求
获取code后用code_verifier换取access_token
使用access_token获取SaaS-URl地址

🚦 三、完整授权流程

步骤一：生成临时密钥

客户端需生成一个随机字符串code_verifier，并按如下方式计算出code_challenge:

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

📌 通常推荐使用 SHA-256 算法，并使用 Base64URL 编码

python示例：

python

# 生成随机 code_verifier
code_verifier = base64.urlsafe_b64encode(os.urandom(64)).rstrip(b'=').decode('utf-8')

# 生成 code_challenge（SHA256 + Base64URL 编码）
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).rstrip(b'=').decode('utf-8')

步骤二：跳转用户进行授权

接口地址：

bash

GET https://saas.api.yoo-ai.com/oauth/authorize

请求参数说明：

Header

Token在前面准备工作中获取。创建saas应用后，配置信息获取

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer Token	Bearer Yoo-xxxxxxxxx

Query

参数	类型	必填	说明
app_id	String	Y	应用ID，在韦尼克平台创建SaaS应用后获得
response_type	string	Y	固定为`code`
state	string	Y	客户端生成的随机字符串，用于防止 CSRF
code_challenge	string	Y	步骤一生成的 `code_challenge`
redirect_uri	string	Y	安全域名，授权成功后跳转地址，需与应用配置一致

示例请求：

shell

curl --location --request GET 'https://saas.api.yoo-ai.com/oauth/authorize?app_id=8295936608&response_type=code&state=*****&code_challenge=*****&redirect_uri=https://b.yoo-ai.com'

返回结果

HTTP 302 重定向至授权页，用户完成授权后跳转至你配置的 redirect_uri，URL 中携带参数：

bash

https://b.yoo-ai.com/?code=*****&state=*****

📌 请注意：应从跳转后的 redirect_uri 中提取 code 参数

步骤三：通过 code 获取 access_token

接口地址：

bash

POST https://saas.api.yoo-ai.com/oauth/token

请求参数说明：

Header

Token在前面准备工作中获取。创建saas应用后，配置信息获取

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer Token	Bearer Yoo-xxxxxxxxx

参数名	取值	说明
Content-Type	application/json	请求正文的方式。

Body

参数	类型	必填	说明
code	String	Y	上一步授权回调中获取的 `code` 参数
app_id	String	Y	应用ID，在韦尼克平台创建SaaS应用后获得
code_verifier	String	Y	第一步生成的原始随机字符串
expire_date	Int	N	令牌过期时间（单位：Unix 秒时间戳，默认 86400 秒 = 1 天）
union_id	string	N	子用户ID【详情】

示例请求：

bash

curl --location --request POST 'https://saas.api.yoo-ai.com/oauth/token' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ******' \
--header 'Accept: */*' \
--header 'Host: saas.api.yoo-ai.com' \
--header 'Connection: keep-alive' \
--data-raw '{
    "code":"*****",
    "app_id":"*****",
    "code_verifier":"******"
}'

响应参数

参数	说明
access_token	调用 API 所需的访问令牌
refresh_token	用于刷新 access_token（30 天有效）
expire_date	访问令牌过期时间，格式为 Unix time 时间戳，精度为秒

示例响应：

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "access_token": "******",
        "refresh_token": "*****",
        "expire_date": 1754550781,
        "union_data": null
    },
    "request_id": ""
}

步骤四：通过access_token获取SaaS-URl地址

接口地址：

bash

POST https://saas.api.yoo-ai.com/oauth/saas-url

请求参数说明：

Header

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer access_token	Bearer xxxxx

响应参数

字段	类型	说明
saas_ppt	String	SaaS访问url地址。（单次使用生效，重新使用需再次请求）

响应示例

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "saas_ppt": "https://ppt.yoo-ai.com?code=*****"
    },
    "request_id": "YOO-saas68930005f13e6"
}

步骤五（可选）：刷新access_token

refresh_token 有效期为 30 天。有效期内可以凭 refresh_token 调用API 刷新 OAuth Access Token

接口地址：

bash

POST https://saas.api.yoo-ai.com/oauth/token

请求参数说明：

Header

Token在前面准备工作中获取。创建saas应用后，配置信息获取

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer refresh_token	Bearer xxxxx

参数名	取值	说明
Content-Type	application/json	请求正文的方式。

Body

参数	类型	必填	说明
code	String	Y	上一步授权回调中获取的 `code` 参数
app_id	String	Y	应用ID，在韦尼克平台创建SaaS应用后获得
code_verifier	String	Y	第一步生成的原始随机字符串
expire_date	Int	N	令牌过期时间（单位：Unix 秒时间戳，默认 86400 秒 = 1 天）
union_id	string	N	子用户ID【详情】

响应参数

参数	说明
access_token	调用 API 所需的访问令牌
refresh_token	用于刷新 access_token（30 天有效）
expire_date	访问令牌过期时间，格式为 Unix time 时间戳，精度为秒

示例响应：

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "access_token": "******",
        "refresh_token": "*****",
        "expire_date": 1754550781,
        "union_data": null
    },
    "request_id": ""
}

📌 常见问题（FAQ）

Q1：app_id 从哪里获取？

请在韦尼克平台中“创建应用”后复制，例如：Yoo-AI.415.2ZMSvPdvxxxxxxxxxxxxxxxxxxx

Q2：code_challenge 和 code_verifier 要自己生成吗？

是的。前端或后端需要自行实现或调用标准库（如 crypto-js）进行计算。

🧩 Saas授权接入指南 ​

📘 一、准备工作 ​

🔐 二、授权机制概述（OAuth + PKCE） ​

🚦 三、完整授权流程 ​

步骤一：生成临时密钥 ​

步骤二：跳转用户进行授权 ​

步骤三：通过 code 获取 access_token ​

步骤四：通过access_token获取SaaS-URl地址 ​

步骤五（可选）：刷新access_token ​

📌 常见问题（FAQ） ​

相关文档 ​

🧩 Saas授权接入指南

📘 一、准备工作

🔐 二、授权机制概述（OAuth + PKCE）

🚦 三、完整授权流程

步骤一：生成临时密钥

步骤二：跳转用户进行授权

步骤三：通过 code 获取 access_token

步骤四：通过access_token获取SaaS-URl地址

步骤五（可选）：刷新access_token

📌 常见问题（FAQ）

相关文档