开发者平台

云客服登录开发指南

前期准备

网站应用须在云客服后台创建客户端应用，方可利用云客服授权联合登录系统，整个流程基于标准的OAUTH2.0协议。

设置 > OAUTH客户端

授权步骤

1. 第三方发起云客服授权登录请求，用户允许授权第三方应用后，云客服重定向到第三方网站，URL附上临时授权码code参数；

2. 第三方通过code加上client_id等参数，请求access_token；

3. 第三方通过access_token，获取用户基本数据资源或帮助用户实现基本操作。

access_token 获取时序图：

第一步：获取 code 临时授权码

临时授权码有效期为 10 分钟，可凭借此授权码向云客服请求 access_token。

https://{yourdomain}.kf5.com/authorize/start?response_type=code&client_id={client_id}&state={state}&redirect_uri=https%3A%2F%2Fclient.abc.com%2Fcb

假设回调 redirect_uri 为：

https://client.abc.com/cb

请求参数

正确响应

成功将返回临时授权码，从回调接口中通过 code 参数获得。

                https://client.abc.com/cb?state={state}&code={code}

错误响应

失败后可以通过 error 以及 error_description 了解本次授权失败的原因。

                https://client.abc.com/cb?state={state}&error=invalid_request&error_description=invalid_request

第二步：授权码 code 请求 access_token

通过第一步获取的 code，请求 access_token，会同时返回 refresh_token，请妥善保管。

    POST /oauth/token HTTP/1.1
Host: {youdoamin}.kf5.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA

认证方式

BASIC AUTH 认证，username 和 password 分别为 client 注册时生成的『OAUTH客户端唯一标识』和『通信秘钥』。

请求参数

正确响应

                    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTMxMDgsInVpZCI6Ijc0NCIsInNjb3BlcyI6InJlYWQsdGlja2V0OndyaXRlIiwiaWQiOiIxMDAwMDExIn0.BFy35PGyQr0OS7ZxPYFiI_VkiYj7fjkweF1bCIETGkE",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI"
}

响应参数

错误响应

                    {
    "error":"invalid_grant",
    "error_description":"The Authorization code is invalid"
}

用 refresh_token 刷新 access_token

access_token 过期后，用 refresh_token 刷新 access_token。

                    POST /oauth/token/refresh HTTP/1.1
Host: {youdoamin}.kf5.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI

请求参数

正确响应

                    {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTMxMDgsInVpZCI6Ijc0NCIsInNjb3BlcyI6InJlYWQsdGlja2V0OndyaXRlIiwiaWQiOiIxMDAwMDExIn0.BFy35PGyQr0OS7ZxPYFiI_VkiYj7fjkweF1bCIETGkE",
    "token_type": "bearer",
    "expires_in": 3600,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwczpcL1wvZGF3bi5rZjUuY28iLCJhdWQiOiJodHRwOlwvXC9kYXduLmtmNS5jb1wvY2xpZW50XC9pbmRleCIsImlhdCI6MTUwODIwOTUwOCwibmJmIjoxNTA4MjA5NTY4LCJleHAiOjE1MDgyMTY3MDgsImlkIjoiMTAwMDAxMSJ9.UpnsxNRe-AO9nUcfQiwXU1nVaDjoAMOLYzkqbq_tqpI"
}

错误响应

                    {
    "error":"invalid_grant",
    "error_description":"refresh token is invalid"
}

第三步：用 access_token 调用资源接口

用 access_token 调用资源接口，调用成功的前提是，access_token 有效，且接口对应的 授权域 包含在 access_token 的授权域中。

支持接口如下：

client 授权域

协议规范中叫 scope，用于 OAUTH 授权访问时的权限控制。user:read 为基础授权域，若授权时仅指定了其他授权域将自动包含该域，目前仅支持 user:read。

OAUTH 授权错误汇总