开发者文档

授权流程

1、Authorization Code授权流程

采用Authorization Code获取Access Token的授权验证流程又被称为Web Server Flow，适用于所有有Server端的应用，如Web/Wap站点、有Server端的手机/桌面客户端应用等。

应用场景：大部分第三方应用接入者；如果第三方开发者开发没有server端不建议使用此类型授权方式。

强烈建议使用该方式进行接口调用，并且申请该方式的接口调用审核较其他方式宽松。

流程图

请求流程

根据上述流程图，授权请求分为2步骤：

开发者发起请求 https://api.17wanxiao.com/api/authorize 打开用户登录页面，让用户登录。用户登录成功，获取临时token，获取后使用临时token和申请client_id和client_secret获取资源访问令牌：access_token。

步骤1：用户登录，同意授权，获取临时token: code

接口说明：这个接口返回是一个web 页面，要求完美校园用户登录和授权。
接口协议：HTTPS URL 结构：https://api.17wanxiao.com/api/authorize (测试地址)

请求接口参数：

请求示例：

                    
                    https://api.17wanxiao.com/api/authorize

                    client_id=CLIENT_ID&

                    response_type=code&

                    redirect_uri=REDIRECT_URI&

                    state=STATE&

                    reLogin=TRUE&

                    display=1

                    
                    

注意：大写字段替换成自己的对应变量值

此页面中会要求用户登录，然后选择同意或者拒绝对应用授权。如果用户同意授权，授权成功后，web 应用会重定向到 redirect_uri参数所指定的 URL（含返回参数）。

返回成功示例：

  https:// REDIRECT_URI?code=CODE

若用户禁止授权，则重定向后不会带上code参数

步骤2：通过code换取访问令牌：access_token

接口说明：用临时 code 换取 access token
接口协议：HTTPS POST URL 结构：https://api.17wanxiao.com/api/accessToken (测试地址)

请求接口参数

请求示例(为方便示例使用GET, 发送真实请求请使用POST)：

https://api.17wanxiao.com/api/accessToken?

code=CODE&

client_id=CLIENT_ID&

client_secret =CLIENT_SECRET&

redirect_uri=REDIRECT_URI

grant_type= authorization_code

注意：大写字段替换成自己的对应变量值，缩进仅为了更好展示

接口返回：

返回 HTTP 的状态码含义，请参考 附录 HTTP 状态码。

若 HTTP 状态码为 200，消息体返回参数（当前只支持返回 JSON 化字符串）：

返回参数

返回示例：

                        
                        {
                        "access_token":"ACCESS_TOKEN",
                        "expires_in":3600,
                        "refreshToken":"REFRESH_TOKEN"
                        }
                    

2、Implicit Grant授权流程

采用Implicit Grant方式获取Access Token的授权验证流程又被称为User-Agent Flow，适用于所有无Server端配合的应用（由于应用往往位于一个User Agent里，如浏览器里面，因此这类应用在某些平台下又被称为Client-Side Application），如手机/桌面客户端程序、浏览器插件等，以及基于JavaScript等脚本客户端脚本语言实现的应用，他们的一个共同特点是，应用无法妥善保管其应用密钥（App Secret Key）。

建议该方式实在无server端的应用时使用该方式调用， 此种授权安全性比其他方式的安全性低。在审核此种应用时会比较严格。

流程图

请求流程

根据上面流程图，授权请求只有1步骤：

开发者发起请求https://api.17wanxiao.com/api/authorize 打开用户登录页面，让用户登录。 如果用户登录成功，直接跳转到开发者提供的回调地址，回调地址附加access token

步骤1：用户登录，同意授权

接口说明：这个接口返回是一个 web 页面，要求完美校园用户登录和授权。
接口协议：HTTPS URL 结构：https://api.17wanxiao.com/api/authorize (测试地址)

请求接口参数：

请求示例：

                        
                        https://api.17wanxiao.com/api/authorize

                        client_id=CLIENT_ID&

                        response_type=code&

                        redirect_uri=REDIRECT_URI
                        
                    

注意：大写字段替换成自己的对应变量值

此页面中会要求用户登陆，然后选择同意或者拒绝对应用授权。
如果用户同意授权,授权成功后:web 应用会重定向到 redirect_uri 所指定的 URL（含返回参数）。
返回成功示例：

    https:// REDIRECT_URI#access_token=ACCESS_TOKEN&expires_in=EXPIRES_IN

若用户禁止授权，则重定向后不会带上access_token参数和expires_in参数。
注意：这里返回的access_token和expires_in不是url参数，以#号分割。

3、Client Credentials授权流程

采用Client Credentials方式获的Access Token为开发者的access_token访问令牌，该access_token不能获取用户相关的信息，即不能调用用户相关的API，但是可以调用开发者相关的API , 该授权访问类型就是为了开发者访问自身相关的API而存在的。

使用场景：第三方开发者需要获取自己应用的相关信息。

使用此类型接口，可以调用：开发者授权信息、开发者接口访问次数、接口调用失败次数、该应用的用户列表、开发者用户请求统计等等 。例如： api/1/dev/grant/info接口

流程图

请求流程

根据上面流程图，授权请求只有1步骤： 开发者发起请求https://api.17wanxiao.com/api/accessToken 请求中POST提交client_id和c两个参数

步骤：授权操作获取访问令牌access_token

接口说明：使用此接口直接进行授权。
接口协议：HTTPS POST URL 结构：https://api.17wanxiao.com/api/accessToken (测试地址)

请求接口参数：

请求示例：

                    
                        https://api.17wanxiao.com/api/accessToken?

                        client_id=CLIENT_ID&

                        &client_secret=CLIENT_SECRET

                        &grant_type=client_credentials
                    
                    

注意：大写字段替换成自己的对应变量值,示例使用GET实际请参考上面:接口协议

返回成功示例：

                        
                        {
                        "access_token":"ACCESS_TOKEN",
                        "expires_in":3600
                        }

4、refresh_token换取access_token

在使用Authorization_Code 认证方式获取access_token 时会返回一个refresh_token 该refresh_token默认为14天有效期。在refresh_token的作用是：当access_token失效后可以使用refresh_token， 换取新的access_token。 因此它起到的效果就是：当用户对应用进行授权后，应用在用户第二次或者后续访问时不需要用户进行授权即可获取该用户的信息。 在access_token失效后，如果想再次获取用户信息，则可使用refresh_token换取access_token来访问用户的数据信息。

注意当使用refresh_token获取一次access_token后，原来的access_token和refresh_token都会失效，并重新返回新的access_token和refresh_token

请求流程
根据上面流程图，授权请求只有1步骤：开发者发起请求https://api.17wanxiao.com/api/accessToken

步骤：授权操作获取访问令牌access_token

接口说明：使用此接口直接进行授权。
接口协议：HTTPS POST URL 结构：https://api.17wanxiao.com/api/accessToken (测试地址)

请求接口参数：

请求示例：

                        
                        https://api.17wanxiao.com/api/accessToken?

                        client_id=CLIENT_ID&

                        client_secret=CLIENT_SECRET&

                        grant_type=refresh_token&

                        refresh_token=REFRESH_TOKEN
                        
                    

注意：大写字段替换成自己的对应变量值,示例使用GET实际请参考上面:接口协议

返回成功示例：

                        
                        {
                        "access_token":"ACCESS_TOKEN",
                        "expires_in":3600,
                        "refreshToken":"REFRESH_TOKEN"
                        }