Oauth2.0 API
Fanbook Developer
正式：https://a1.fanbook.cn/open/
Oauth2.0#
使用票证的授权方式#
Oauth 序列图02#
应用
获取应用信息#
请求格式：
• Method：GET
• Path：/open/oauth2/app
Header 参数
| 参数名 | 描述 |
|---|---|
| authorization | Fanbook 会话 token |
Query 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| client_id | string | 是 | |
| redirect_url | string | 否 | 授权后跳转的地址 |
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| app | Application | 是 | 应用信息 |
| user | User | 是 | 授权用户信息 |
打开授权页面（**For Web**）#
请求格式：
• Method：GET
• Path：/open/oauth2/authorize
Header 参数
| 参数名 | 描述 |
|---|---|
Query 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| response_type | string | 是 | 固定值：code |
| client_id | string | 是 | |
| state | string | 否 | 自定义状态数据，传入的值会直接返回 |
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
确认授权#
请求格式：
• Method：POST
• Path：/open/oauth2/authorize
Header 参数
| 参数名 | 描述 |
|---|---|
| authorization | Fanbook 会话 token |
Query 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| response_type | string | 是 | 固定值：code |
| client_id | string | 是 | |
| allow | bool | 是 | 授权行为，true: 允许，false: 拒绝 |
| status_code | string | 否 | 自定义 response status code，默认返回 302，可选值：[200, 302] |
| state | string | 否 | 自定义状态数据，传入的值会直接返回，一般用于安全验证，前端可以验证服务器的返回是否一致，可以是用户session的hash值，或者是可以唯一标识会话的任意值。 |
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| location | string | 是 | 重定向地址 |
换发 Token#
请求格式：
• Method：POST
• Path：/open/oauth2/token
Header 参数
| 参数名 | 描述 |
|---|---|
| content-type | application/x-www-form-urlencoded |
| authorization | Basic {base64_encode(client_id:client_secret)} |
注意这里的content-type。另外authorization的生成，如果client_id为"123456"，client_secret为"aSecret"，那么authorization应为 "Basic MTIzNDU2OmFTZWNyZXQ="
Body 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| grant_type | string | 是 | 固定值：authorization_code |
| code | string | 是 | 通过授权获得到 code，一次使用有效 |
| redirect_uri | string | 是 | 创建应用时预先设置的跳转地址 |
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| access_token | string | 是 | |
| refresh_token | string | 是 | |
| token_type | string | 是 | 固定值：bearer |
| expires_in | int | 是 | |
| scope | Token 适用的 scope |
刷新 Token#
请求格式：
• Method：POST
• Path：/open/oauth2/refresh
Header 参数
| 参数名 | 描述 |
|---|---|
| content-type | application/x-www-form-urlencoded |
| authorization | Basic {base64_encode(client_id:client_secret)} |
Body 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| grant_type | string | 是 | 固定值：refresh_token |
| refresh_token | string | 是 | |
| redirect_uri | string | 是 | - |
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| access_token | string | 是 | |
| refresh_token | string | 是 | |
| token_type | string | 是 | 固定值：bearer |
| expires_in | int | 是 | |
| scope | Token 适用的 scope |
使用implicit的授权方式#
时序图#
接口说明#
打开授权页面（**For Web**）#
请求格式：
• Method：GET
• Path：/open/oauth2/authorize
Header 参数
| 参数名 | 描述 |
|---|---|
Query 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| response_type | string | 是 | 固定值：token |
| client_id | string | 是 | |
| state | string | 否 | 自定义状态数据，传入的值会直接返回 |
| redirect_uri | string | 是 | 重定向地址，一定要跟申请应用时填写的重定向地址一致，否则会返回错误信息，授权失败 |
| scope | string | 是 | 授权权限的枚举，多个权限值直接必须使用“%20” 连接，比如user.link%20user.info，下文有对权限的描述 |
| status_code | string | 否 | 指定返回时使用的状态码，默认是返回302，可以指定为200，则会返回的body里带上location，即重定向后的地址 |
返回数据：
默认会在返回的header里包含了location字段，字段内容示例如下： http://localhost/#access_token=z7Aj7v/qN7T//uQq1ohquw==&token_type=Bearer&expires_in=3599&scope=user.link%20user.info&state=3
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| access_token | string | 是 | 返回的token信息 |
| token_type | string | 是 | token的类型，目前为固定值"Bearer" |
| expires_in | string | 是 | 有效时间，默认为3600秒 |
| scope | string | 是 | 授权权限的枚举，多个权限值直接必须使用“%20” 连接，比如user.link%20user.info |
| state | string | 否 | 自定义状态数据，返回请求里填充的state值 |
获取用户个人数据#
请求格式：
• Method：POST
• Path：/open/api/user/getMe
Header 参数
| 参数名 | 描述 |
|---|---|
| content-type | application/json |
| authorization | Bearer {access_token} |
JSON 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| status | bool | 是 | |
| data | User | 否 | |
| message | string | 否 |
获取个人服务器列表#
请求格式：
• Method：POST
• Path：/open/api/guild/getGuilds
Header 参数
| 参数名 | 描述 |
|---|---|
| content-type | application/json |
| authorization | Bearer {access_token} |
JSON 参数
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
返回数据：
| 参数名 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| status | bool | 是 | |
| data | Array of Guild | 否 | |
| message | string | 否 |
Open API Types#
User#
用户个人信息
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| user_id | string | 是 | 用户全局唯一 ID |
| nickname | string | 是 | 用户昵称 |
| username | string | 是 | 用户可读标识 ID |
| avatar | string | 是 | 头像 |
| token | string | 否 |
Application#
应用信息
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| client_id | string | 是 | 应用 ID |
| description | string | 是 | 应用简介 |
| icon | string | 是 | 应用 ICON 标识地址 |
| name | string | 是 | 应用名称 |
| scopes | string | 是 | 应用申请的权限范围 |
GuildCredit#
用户服务器荣誉数据
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| authority | CreditAuthority | 否 | 荣誉颁发者 |
| title | CreditTitle | 否 | 荣誉 title，展示在聊天会话中的个人头像右侧 |
| slots | Array of CreditSlot array | 是 | 荣誉槽，展示在个人信息页，是二维数组 |
CreditAuthority#
服务器荣誉颁发者详情
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| icon | string | 是 | 荣誉颁发者形象 logo url 地址 |
| name | string | 是 | 荣誉颁发者名称 |
CreditTitle#
服务器荣誉 Title
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| img | string | 否 | 荣誉 Title 图形 url 地址 |
CreditSlot#
服务器荣誉槽
| 字段 | 类型 | 是否必须 | 描述 |
|---|---|---|---|
| label | string | 是，与 img 二选一 | 荣誉文本标题 |
| img | string | 是，与 label 二选一 | 荣誉图形标题 |
| value | string | 是 | 荣誉值本值 |
Open API 签名方法#
权限定义#
| 权限 | 描述 |
|---|---|
| user.info | 用户的基本信息，用户nickname和avatar等等 |
| user.link | 用户的电话号码 |