一、鉴权方式介绍

K歌的开放平台对第三方平台分配appid和secret，然后三方平台获取到接口调用凭证（access_token），以及K歌用户账号对外的开放身份ID（openid），并通过接口调用凭证调用K歌对外提供的业务接口。
K歌的鉴权方式分为了两种：

应用级鉴权

用户级鉴权

应用级鉴权：校验的是应用级access_token，应用级access_token由三方平台服务端来调用获取，并由三方平台服务端来存储和维护其状态。同一个appid同一时间只能有一个合法的应用级access_token，并且它有效期，所有不适在客户端使用。
应用级access_token不能请求用户类的接口和播放的接口。
适用场景：游客态请求一些歌单类接口。
用户级鉴权：校验的是用户级access_token+openid。用户级access_token和openid可以下发到客户端，由客户端直接调用K歌业务接口，但用户的refresh_token建议存放在服务端，并有服务端来维护。用户级access_token是针对一个用户而言，同一个appid同一时间同一用户只能有一个合法的用户级access_token，所以即使token被泄漏，影响也有限。
用户级token需要扫码登录后才能获取。
适用场景：客户端使用，只有用户级token可请求播放的接口，用于K歌播放。
注意⚠️：
1、使用【应用级token】，请求头X-Open-Id 不能传值。否则会认为票据无效。
2、如果客户端有未登录的使用场景，请通过业务后台进行转发。

域名

正式环境：https://api.kg.qq.com/api
体验环境：https://api.kg.qq.com/test/api

二、授权api相关接口介绍

1、获取应用级token(getToken)

该接口第三方后台调用，使用appid和appsecret获取应用级token。一个appid同一时间只能有一个合法的应用级access_token，所以此token只能放于后台，不能直接用于客户端。
注意: refresh_token的有效期不返回，一般为30天。

请求URL

请求方式：POST

正式环境：https://api.kg.qq.com/api/v2/getToken
体验环境：https://api.kg.qq.com/test/api/v2/getToken

请求参数

参数类型：Content-Type: application/json

参数名	必选	类型	说明
appid	是	string	业务透传过来，应用appid
secret	是	string	应用秘钥
grant_type	是	string	获权类型, 固定填 client_credential

返回参数

参数名	类型	说明
access_token	string	access_token
expires_in	int	access_token有效期
refresh_token	string	refresh_token 刷新access_token时使用
error_code	int	错误码
error_msg	string	error_code非0时的错误消息

2、获取用户级token(access_token)

该接口由第三方后台调用，可以获取用户级授权token，openid等信息。
注意: refresh_token的有效期不返回，一般为30天（最长可延长至180天）。

请求URL

请求方式：POST

正式环境：https://api.kg.qq.com/oauth/v2/access_token
体验环境：https://api.kg.qq.com/test/oauth/v2/access_token

请求参数

参数格式：Content-Type: application/json

参数名	必选	类型	说明
appid	是	string	业务透传过来，应用appid
secret	是	string	应用秘钥
code	是	string	授权码，authcode
grant_type	是	string	获权类型, 固定填 authorization_code

返回参数

参数名	类型	说明
access_token	string	access token
expires_in	int	access token有效期
refresh_token	string	refresh token 刷新access token时使用
openid	string	openid
unionid	string	unionid
scope	string	本次授权范围
orig_acnt_type	int	(需要应用具备该权限才会返回)账号原始类型(1 QQ; 2 微信;)
error_code	int	错误码
error_msg	string	error_code非0时的错误消息

3、刷新access_token(refresh_token)

使用refreshToken，刷新AceessToken。刷新AccessToken的时候，原来的还在有效期内的AccessToken在1分钟内依然有效，方便新老AccessToken过渡，建议在AccessToken快过期前10分钟就刷新。

请求URL

请求方式：POST

正式环境：https://api.kg.qq.com/oauth/v2/refresh_token
体验环境：https://api.kg.qq.com/test/oauth/v2/refresh_token

请求参数

参数格式：Content-Type: application/json

参数名	必选	类型	说明
appid	是	string	业务透传过来，应用appid
openid	否	string	用户openid。仅刷新用户级token需要
refresh_token	是	string	用户的refresh_token
sign	是	string	应用接口请求签名，计算规则如下
ts	是	int	时间戳(单位s)

接口签名（sign）的计算规则

sign的计算规则如下：
sign = md5(KG_APPID_TS_SECRET)
比如, appID为10001, 时间戳为1675748252，secret为xxxabc
那么要加密的字符串为 KG_10001_1675748252_xxxabc
再对字符串进行md5计算得到签名(32位小写)
示例代码如下：

   fun sign(ts: Long): String {
       val str = "KG_" + appId + "_" + ts + "_" + appKey
            return MD5Util.md5(str)
   }

返回参数说明

参数名	类型	说明
access_token	string	刷新获得的AccessToken
expires_in	int	AccessToken有效期
error_code	int	错误码
error_msg	string	error_code非0时的错误消息

建议的刷新方式：

请求时检查token用了多久了，比如用了1个小时，就刷新一次。

token过期时刷新(碰到40002、40004错误码)

4、获取授权码(light_qr_code)

请求url

请求方式：POST

正式环境：https://api.kg.qq.com/oauth/v2/light_qr_code
测试环境：https://api.kg.qq.com/test/oauth/v2/light_qr_code

请求参数

Content-Type: application/json

参数名	必选	类型	说明
appid	是	string	业务透传过来，应用appid
response_type	是	string	固定填 code
scope	是	string	固定填snsapi_login
sign	是	string	应用接口请求签名，参考refresh_token生成方式
ts	是	int	当前时间戳(单位s)
business_data	否	string	二码合一支付透传数据
scan_side_redirect_uri	否	string	扫码端登录成功后跳转地址

返回参数说明

参数名	类型	说明
qr_code	string	二维码
expires_in	int	二维码有效期
qr_sig	string	二维码签名
error_code	int	错误码
error_msg	string	error_code非0时的错误消息

二维码使用说明

获取到qr_code和qr_sig之后，按格式http://kg.qq.com/m.html?sig=QR_SIG&code=QR_CODE拼接字符串，并生成二维码内容，例如：

http://kg.qq.com/m.html?sig=626dd9441e4fb3ea764c92fc4ca75405&code=39c2f286767966e4614f76deb4cbcaa360b8a698b5b3b9ca9bce4afc6284f5e53af9856af3b5

5、获取授权码状态(light_qr_stat)

请求url

请求方式：POST

正式环境：https://api.kg.qq.com/oauth/v2/light_qr_stat
测试环境：http://api.kg.qq.com/test/oauth/v2/light_qr_stat

请求参数说明

Content-Type: application/json

参数名	必选	类型	说明
code	是	string	二维码
sig	是	string	二维码签名
appid	是	string	应用ID
sign	是	string	应用接口请求签名，参考refresh_token计算方式
ts	是	int	时间戳

返回参数说明

参数名	类型	说明
stat	int	二维码状态
data	string	授权码
scan_source	int	扫码来源
error_code	int	错误码
error_msg	string	error_code非0时的错误消息

二维码状态说明

状态	说明
11	待扫码
12	已扫码，待确认
13	已扫码，已确认 (只有此时会返回授权码，且此状态只触发一次)
14	扫码完成登录

扫码来源说明

来源	说明
0	未知
1	全民K歌
2	微信
3	QQ

三、流程方案介绍

应用级token的获取比较简单，本节只介绍用户级token的获取方案。

✨方案三（推荐）：

方案特点：

可以自定义UI样式；

使用上比较麻烦；

可以监测二维码的扫码过程，可以使用K歌app扫码。
登录流程如下：

步骤一：

三方调用light_qr_code获取code和sig值，然后拼接好二维码的内容，再向用户展示二维码。

拼接格式：

http://kg.qq.com/m.html?sig=xxx&code=xxx

测试环境的时候，需要在列表后边拼接exp=1

步骤二：

三方通过接口light_qr_stat监听二维码的扫码状态。根据stat字段，获取二维码的状态。并可以进行相应的提示。如果light_qr_stat返回状态（13:已扫码，已确认），则获取light_qr_stat接口返回的data（授权码）字段。

步骤三：

获取到用户授权码后，调用/access_token接口获取用户的openid以及access_token。

✨方案一：

为了方便三方平台的接入，K歌提供了一套便捷的套餐，适合对客户端展示的二维码样式没有要求的平台。

方案特点：

快速方便。回调地址可以配置自定义的scheme；

无法自定义UI样式。

第一步：加载二维码

三方客户端需要使用webview加载下面的url：

https://kg.qq.com/node/openoauth?appid={appid}&redirect_uri={url}&response_type=code&scope=snsapi_login&state={state}

参数说明：

参数名	必选	说明
appid	是	应用id
redirect_uri	是	回调地址，请使用urlEncode对链接进行处理
response_type	是	填"code"
scope	是	网页应用目前仅填写snsapi_login
state	否	用于保持请求和回调的状态，授权请求后原样带回给第三方
exp	否	认请求到正式环境，填“1”表示请求到测试环境

其中，redirect_uri需要在K歌开放平台进行配置，可以配置多个正式环境和测试环境的重定向地址，链接后面可以加参数。exp=1返回测试环境的code，用于获取测试环境的access_token。
例子：

https://kg.qq.com/node/openoauth?appid=100043&redirect_uri=https%3A%2F%2Fwww.tlkg.com%2Fthirdparty%2Ftencent%2Fkg%2Fauthorization&response_type=code&scope=snsapi_login&state=a-b-c-d

第二步：用户扫码确认

用户使用微信/QQ/全民K歌等app进行扫码，在H5中点击授权登录。用户授权后，K歌开放平台会在
redirect_uri后面加一个参数code。
例子：

扫码成功后将重定向到:
https://www.tlkg.com/thirdparty/tencent/kg/authorization?code=39c2f2844a2b35fd303d04d6c7a6c9bf68b984f3b6baeda59abb&state=a-b-c-d

第三步：客户端处理code

客户端的webview通过拦截加载的重定向地址，获取到地址中的code值。随后再与三方自己的后台交互，有三方后台调用K歌授权api相关的接口完成用户access_token、openid、refresh_token的获取。获取到调用凭证后，三方后台可以向客户端下发access_token和openid相关信息，并维护refresh_token的有效期。

✨方案二：

本方案适合对扫码登录二维码样式有要求的三方平台，并且三方平台由自己的账号。该方案需三方平台自己开发登录页面。

方案特点：

可以自定义UI样式；

使用上稍微有点复杂；

无法监测二维码的扫码过程；

无法使用K歌app扫码。

步骤一：生成二维码

三方平台需要自己处理UI相关的工作，生成扫码所需要的二维码，二维码的内容为：

https://kg.qq.com/node/openoauth/authorize?appid={appid}&redirect_uri={url}&response_type=code&scope=snsapi_login&state={state}

参数说明：

参数名	必选	说明
appid	是	应用id
redirect_uri	是	回调地址，请使用urlEncode对链接进行处理
response_type	是	填"code"
scope	是	h5目前填写snsapi_login
state	是	用于保持请求和回调的状态，授权请求后原样带回给第三方
exp	否	默认请求到正式环境，填“1”表示请求到测试环境
wx_scope	否	微信授权范围，不填默认为snsapi_userinfo

其中，redirect_uri需要在K歌开放平台进行配置，可以配置多个正式环境和测试环境的重定向地址，链接后面可以加参数。exp=1返回测试环境的code，用于获取测试环境的access_token。

步骤二：用户扫码确认

同方案一

步骤三：服务端处理code

用户在手机端授权登录后，手机端会重定向到redirect_uri，并且附带code以及state参数过去。三方后台收到redirect_uri的GET请求后，通过code获取到K歌开放平台用户级token相关的信息，并通过state关联到客户端的登录请求。

四、登录态维护

应用级token维护

三方后台维护access_token的有效期，建议在过期前半小时就提前进行刷新。刷新可以重新调用getToken接口或者refresh_token接口。

用户级token维护

access_token的有效期为2小时（登录接口有返回过期时间）：建议在过期前半小时就用refresh_token提前请求新的access_token.
refresh_token的有效期一般为一个月，过期前可用于请求新的access_token。当/refresh_token接口请求失败后，一般为refresh_token过期了，这时需要重新扫码登录。

五、错误码

以下是调用开放平台授权api接口可能返回的错误码，以及错误说明：

错误码	说明
0	成功
1503	未知错误, 可重试
1504	解包错误
1505	打包错误
1506	命令字无法处理
3001	参数无效或者参数不完整
3002	二维码已被使用
3003	签名错误
3004	未带签名
3005	过期
3006	二维码无效
3007	授权码无效
3008	未知授权范围
3009	未知回包类型
3010	未知获权类型
3011	无法获取到客户端IP
3012	禁止访问, referer检查或者csrf攻击检查不通过
3013	应用或者秘钥无效
3014	内部存储获取失败, 可重试
3015	应用APPID不存在
3016	应用分配重复，不可重试，致命错误，请反馈
3017	票据不存在，过期或者已被覆盖
3018	用户未注册
3019	暂不支持扫码方式

当三方平台通过接口调用凭证调用K歌业务接口时，可能返回一下两个错误码：

错误码	说明
40002	鉴权不通过, access_token错误或者过期
40003	鉴权参数不完整, 缺少鉴权相关的必要参数
40004	token失效，失效原因：互踢

六、常见问题

1、openid是唯一的吗？
对于同一个appid来说，openid是唯一的，并且同一个用户的openid是固定的。
2、用户授权后提示“授权失败(user unregistered)”
出现这种提示说明这是一个未在K歌平台注册过的新用户，K歌平台此时还不存在用户的相关账号信息。如果有需要，可以联系我们开通账号自动注册功能。
3、如何区分一个接口应该使用应用级token还是用户级token？
和用户相关的接口必须使用用户级token，其他接口可以使用应用级token或者用户级token。
4、应用级token也有必要使用refresh_token刷新吗？
应用级token可以直接调用getToken接口刷新，也可以使用refresh_token刷新。从降低复杂度角度，建议使用getToken刷新。
5、如何调用测试环境的接口？
无论是开放平台的授权api接口，还是K歌业务接口，都是在正式环境接口url的域名“api.kg.qq.com”后加一个“/test”。
6、access_token的有效期是多久？
用户态access_token有效期为2小时，建议过期前使用refresh_token刷新用户态access_token，刷新后有1分钟缓冲期，缓冲期后旧的access_token立即失效。refresh_token的有效期默认30天

登录鉴权方式介绍V2（推荐）

一、鉴权方式介绍#

域名#

二、授权api相关接口介绍#

1、获取应用级token(getToken)#

请求URL#

请求参数#

返回参数#

2、获取用户级token(access_token)#

请求URL#

请求参数#

返回参数#

3、刷新access_token(refresh_token)#

请求URL#

请求参数#

接口签名（sign）的计算规则#

返回参数说明#

4、获取授权码(light_qr_code)#

请求url#

请求参数#

返回参数说明#

二维码使用说明#

5、获取授权码状态(light_qr_stat)#

请求url#

请求参数说明#

返回参数说明#

二维码状态说明#

扫码来源说明#

三、流程方案介绍#

✨方案三（推荐）：#

方案特点：#

步骤一：#

步骤二：#

步骤三：#

✨方案一：#

方案特点：#

第一步：加载二维码#

第二步：用户扫码确认#

第三步：客户端处理code#

✨方案二：#

方案特点：#

步骤一：生成二维码#

步骤二：用户扫码确认#

步骤三：服务端处理code#

四、登录态维护#

应用级token维护#

用户级token维护#

五、错误码#

六、常见问题#

一、鉴权方式介绍

域名

二、授权api相关接口介绍

1、获取应用级token(getToken)

请求URL

请求参数

返回参数

2、获取用户级token(access_token)

请求URL

请求参数

返回参数

3、刷新access_token(refresh_token)

请求URL

请求参数

接口签名（sign）的计算规则

返回参数说明

4、获取授权码(light_qr_code)

请求url

请求参数

返回参数说明

二维码使用说明

5、获取授权码状态(light_qr_stat)

请求url

请求参数说明

返回参数说明

二维码状态说明

扫码来源说明

三、流程方案介绍

✨方案三（推荐）：

方案特点：

步骤一：

步骤二：

步骤三：

✨方案一：

方案特点：

第一步：加载二维码

第二步：用户扫码确认

第三步：客户端处理code

✨方案二：

方案特点：

步骤一：生成二维码

步骤二：用户扫码确认

步骤三：服务端处理code

四、登录态维护

应用级token维护

用户级token维护

五、错误码

六、常见问题