授权码模式
- 建议使用 客户端模式
# 简介
步骤:
- （A）生成"重定向URI"并通过浏览器引导客户访问授权URL。
- （B）用户输入
Pyvio账号和密码登录。 - （C）假设用户给予授权，认证服务器将用户导向客户端事先指定的"重定向URI"（redirection URI），同时附上一个授权码。
- （D）客户端收到授权码，附上早先的"重定向URI"，向认证服务器申请令牌。
- （E）认证服务器核对了授权码和重定向URI，确认无误后，向客户端发送访问令牌（access token）和更新令牌（refresh token）。
# 1.获取授权码
# URL参数
| 参数名 | 说明 | 是否必填 | 最大长度 | 示例 |
|---|---|---|---|---|
| app_id | 开发者唯一标识 | 是 | 32 | 7520b82387784 |
| response_type | 授权类型 | 是 | 8 | code |
| redirect_URL | 重定向URI | 是 | 32 | https://yourdomain.com/callback |
| state | 客户端的当前状态，可以指定任意值，认证服务器会原封不动地返回这个值。 | 是 | 32 | 123456 |
| scope | 申请的权限范围 scope列表 (opens new window) | 是 | 128 | user_read |
# 返回值
- 如果用户接受授予访问权限的请求，则用户将被重定向到 redirect_URL。
code有效期为30分钟，如果超时未使用，需要重新进行获取。- 授权码只能被使用一次，如果需要继续使用，则需要重新获取。
# 请求示例
沙箱环境：
GET https://sandbox-business.pyvio.com/oauth2?response_type=code&app_id=1569641270953589504&redirect_URL=https://yourdomain.com/callback&state=123456&scope=user_read
生产环境：
GET https://business.pyvio.com/oauth2?response_type=code&app_id=1569641270953589504&redirect_URL=https://yourdomain.com/callback&state=123456&scope=user_read
# 返回示例
https://yourdomain.com/callback?code=be16ef454f48&state=123456
# 2.获取令牌
# body请求参数
| 参数名 | 说明 | 是否必填 | 最大长度 | 示例 |
|---|---|---|---|---|
| app_id | 开发者唯一标识 | 是 | 32 | 7520b82387784 |
| app_secret | 开发者密钥 | 是 | 32 | 2039964434a08828828be16ef454f485 |
| grant_type | 授权类型 | 是 | 32 | authorization_code |
| code | 授权码 | 是 | 32 | be16ef454f48 |
# 返回参数
| 参数名 | 说明 | 最大长度 | 示例 |
|---|---|---|---|
| access_token | 令牌 | 1024 | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
| expires_in | 过期时间 | 16 | 1697447592690 |
| refresh_token | 刷新令牌 | 1024 | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
| refresh_token_expires_in | 刷新令牌过期时间 | 16 | 1697195592690 |
# 请求示例
{
"app_id": "7520b82387784",
"app_secret": "2039964434a08828828be16ef454f485",
"grant_type": "authorization_code",
"code": "be16ef454f48"
}
curl --location --request POST '{baseUrl}/oauth/api/v1/token' \
--header 'Request-Id: bcaaf79e-71f3-3abf-f719-4449143c' \
--header 'Sign: DGhen+ndwMlmkTElnzyMlVa+H/YYG/UEF3uqFpgTVhEPEmApDPiqOyZQle6h/NmT39AO3KmQEjIRJuvXx5SzQtw6iYXbkdLX42SffNfjY/VOggcj2u6SGGyNoZbpm/Ttuux5Z48SUK0wnkvcSD8ht4luI++/iy5gnUHgM2AOHtQ=' \
--header 'X-Timestamp: 1666332361000' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_id":"7520b82387784",
"app_secret":"2039964434a08828828be16ef454f485",
"grant_type":"authorization_code",
"code":"be16ef454f48"
}'
// Make sure to add code blocks to your code group
# 返回示例
{
"trace_id": "3c5be383841a0e9d",
"code": "SUCCESS",
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJhY2Nlc3NUb2tlbkV4cGlyZWQiOjE2OTcxOTU1OTI2OTAsImFwcElkIjoiMTU2OTY0MTI3MDk1MzU4OTUwNCIsInVuaXRJZCI6IlVUMjIwODE3MTU2MDEwNzgiLCJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJvcmdDbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJvcmdVbml0SWQiOiJVVDIyMDgxNzE1NjAxMDc4In0.kEouiUWgR-2M3nOA3POEYnVluWGTi2_I3ghYTGHpYrs",
"refresh_token_expires_in": 1697447592690,
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJhY2Nlc3NUb2tlbkV4cGlyZWQiOjE2OTc0NDc1OTI2OTAsImFwcElkIjoiMTU2OTY0MTI3MDk1MzU4OTUwNCIsInVuaXRJZCI6IlVUMjIwODE3MTU2MDEwNzgiLCJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJvcmdDbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJvcmdVbml0SWQiOiJVVDIyMDgxNzE1NjAxMDc4In0.W6-f01j1rcrIrVIRsLa2yY-TSX5OBxuUG1ugJMdqTzg",
"expires_in": 1697195592690
},
"success": true,
"message": null
}
{
"trace_id": "604a5bdacf6f0e90",
"code": "B_Sign_InvalidError",
"success": false,
"message": "app_id is invalid"
}
// Make sure to add code blocks to your code group
# 3.更新令牌
- 通过提供之前存储的刷新令牌，您可以使用此端点获取新的访问令牌和刷新令牌对。
- 如果您丢失了刷新令牌或在刷新访问令牌之前它已过期，您将需要重新开始与用户的授权流程。
# body请求参数
| 参数名 | 说明 | 是否必填 | 最大长度 | 示例 |
|---|---|---|---|---|
| app_id | 开发者唯一标识 | 是 | 32 | 7520b82387784 |
| app_secret | 开发者密钥 | 是 | 32 | 2039964434a08828828be16ef454f485 |
| grant_type | 授权类型 | 是 | 32 | refresh_token |
| refresh_token | 刷新令牌 | 是 | 1024 | 1ENheDxpjS5/be16ef454f48... |
# 返回参数
| 参数名 | 说明 | 最大长度 | 示例 |
|---|---|---|---|
| access_token | 令牌 | 1024 | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
| expires_in | 过期时间 | 16 | 1697447592690 |
| refresh_token | 刷新令牌 | 1024 | eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... |
| refresh_token_expires_in | 刷新令牌过期时间 | 16 | 1697195592690 |
# 请求示例
{
"app_id": "7520b82387784",
"app_secret": "2039964434a08828828be16ef454f485",
"grant_type": "refresh_token",
"refresh_token": "1ENheDxpjS5/YzCiA/IQkntco/PdQ0wFChYs5oMeLz77TOdJmyoJt4r7/fCAjwRg"
}
curl --location --request POST 'https://sandbox-api.pyvio.com/oauth/api/v1/token' \
--header 'Request-Id: bcaaf79e-71f3-3abf-f719-4449143c' \
--header 'Sign: DGhen+ndwMlmkTElnzyMlVa+H/YYG/UEF3uqFpgTVhEPEmApDPiqOyZQle6h/NmT39AO3KmQEjIRJuvXx5SzQtw6iYXbkdLX42SffNfjY/VOggcj2u6SGGyNoZbpm/Ttuux5Z48SUK0wnkvcSD8ht4luI++/iy5gnUHgM2AOHtQ=' \
--header 'X-Timestamp: 1666332361000' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_id":"7520b82387784",
"app_secret":"2039964434a08828828be16ef454f485",
"grant_type":"refresh_token",
"refresh_token":"1ENheDxpjS5/YzCiA/IQkntco/PdQ0wFChYs5oMeLz77TOdJmyoJt4r7/fCAjwRg"
}'
// Make sure to add code blocks to your code group
# 返回示例
{
"trace_id": "3c5be383841a0e9d",
"code": "SUCCESS",
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJhY2Nlc3NUb2tlbkV4cGlyZWQiOjE2OTcxOTU1OTI2OTAsImFwcElkIjoiMTU2OTY0MTI3MDk1MzU4OTUwNCIsInVuaXRJZCI6IlVUMjIwODE3MTU2MDEwNzgiLCJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJvcmdDbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJvcmdVbml0SWQiOiJVVDIyMDgxNzE1NjAxMDc4In0.kEouiUWgR-2M3nOA3POEYnVluWGTi2_I3ghYTGHpYrs",
"refresh_token_expires_in": 1697447592690,
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJhY2Nlc3NUb2tlbkV4cGlyZWQiOjE2OTc0NDc1OTI2OTAsImFwcElkIjoiMTU2OTY0MTI3MDk1MzU4OTUwNCIsInVuaXRJZCI6IlVUMjIwODE3MTU2MDEwNzgiLCJncmFudFR5cGUiOiJjbGllbnRfY3JlZGVudGlhbHMiLCJvcmdDbGllbnRJZCI6IkNUMjIwNzI4MTU2MDAwMTQiLCJvcmdVbml0SWQiOiJVVDIyMDgxNzE1NjAxMDc4In0.W6-f01j1rcrIrVIRsLa2yY-TSX5OBxuUG1ugJMdqTzg",
"expires_in": 1697195592690
},
"success": true,
"message": null
}
{
"trace_id": "604a5bdacf6f0e90",
"code": "B_Sign_InvalidError",
"success": false,
"message": "app_id is invalid"
}
// Make sure to add code blocks to your code group