适用版本

该功能适用版本为苍穹V6.0.1以上

功能速览

以下是增强型Token认证提供的接口列表：

开发人员根据业务需要调用getToken接口获取令牌，然后缓存在调用端，在access_token过期之前（2小时内）可以调用verifyToken接口验证access_token有效性，并获取最新的过期时间。

在access_token过期之前，调用refreshToken接口刷新access_token的有效期，从而在不换access_token的情况下继续调用OpenAPI。

3.1 getToken

功能描述：令牌（access_token）是第三方应用调用OpenAPI的调用凭证，每次请求客户端都需要带上token，通过请求头发送，服务端以此来控制身份，当token过期后，服务端会销毁token，客户端需要重新请求获得token。

请求 URL：http://{{localhost}}/kapi/oauth2/getToken

调用方式：HTTP调用

请求方式：POST

请求类型：Content-Type:application/json

调用频率：1分钟30次

token有效期：2小时

注意事项：

1. 令牌的获取是有限制的，每个令牌的有效期为 2 小时，请自行做好令牌的管理，在令牌快过期时（通过验证接口获取剩余过期时间比如1小时50分），可重新调用接口获取或调用刷新令牌接口来延长令牌有效期。

2. 数据中心accountId，同时支持在Header和Body传输。

请求Body参数：

请求参数示例：

{
    "client_id": "thirdappunittest_003",
    "client_secret": "Abcdrty@1234567890#@2",
    "username":"zhangSan",
    "accountId": "1355633519610561531",
    "language": "zh_CN",
    "nonce": "123",
    "timestamp": "2023-09-08 11:47:00"
}

返回参数：

返回参数示例：

{
"data": {
    "access_token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9FZ3h4MXU1Zzd2Qk9kRjR4MzIxQXZKcXU5c2hpbzNCaTRtTGIzbEsyM3JnbmFJUUJEMEltZUt3UURYQmFFdDJIVnc3MWtyaTVUR01ZbTRDUGVETDVSamE2R0F1a2g5SGpVcmwx",
    "token_type": "Bearer",
    "refresh_token": "d367106c-de46-4fc4-9e1a-59cbcfc430d2",
    "scope": "API",
    "expires_in": "7199977",
    "id_token": "OPENAPIAUTH_ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5Sm1hV1FpT2lJeE16UTJOamN6T1NJc0luTjFZaUk2SW10a2FuZDBJaXdpWm5Cb2IyNWxJam9pTVRjeU9UazVPVGs1T1RraUxDSmxhV1FpT2lJeE1UUTNOVFl4TnlJc0ltWjBjblZsYm1GdFpTSTZJa2xGVWxBaUxDSm1iM0puYVdRaU9pSXhJaXdpWm1WdFlXbHNJam9pYVdWeWNFQnJhVzVuWkdWbExtTnZiU0lzSW1semN5STZJbXRrSWl3aWRYTmxjbWxrSWpvaU1UTTBOalkzTXpraUxDSm1ZbWw2Y0dGeWRHNWxjbWxrSWpvaU1DSXNJbVpzWVhOMGJHOW5hVzVwY0NJNklqRTNNaTR5TUM0eE5DNDJOeUlzSW1acGMyRmpkR2wyWldRaU9pSXhJaXdpWm05d1pXNXBaQ0k2SWpWaE1tUmxabU5pWlRSaU1EazFOMlpoTURobU9HTTNNaUlzSW1ac1lYTjBiRzluYVc1MGFXMWxJam9pTWpBeU15MHdPQzB5T1NBd01Eb3dNRG93TUM0d0lpd2labVZ1WVdKc1pTSTZJakVpTENKbWRXbGtJam9pTVRNME5qWTNNemtpTENKMWMyVnlWSGx3WlNJNklqRWlMQ0psZUhBaU9qRTJPVFEyTURReU1UZ3NJbWxoZENJNk1UWTVORFU1TnpBeE9Dd2labWx6Y21WbmFYTjBaV1FpT2lJeElpd2labkJ6ZDNOMGNtRjBaV2Q1YVdRaU9pSTNOakk1TnpjM09UVTNOekl3TURVek56WWlMQ0oxYzJWeWIzQmxibWxrSWpvaU5XRXlaR1ZtWTJKbE5HSXdPVFUzWm1Fd09HWTRZemN5SWl3aWRYTmxjbTVoYldVaU9pSkpSVkpRSW4wLi1ZZEd1cWhIX25Mcm5ibURnQTlfU2FvQkZsTGJWTTJEUmp2cnR4NXZwckk=",
    "id_token_expires_in": "7199977",
    "language": "zh_CN"
        },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明：

3.2 verifyToken

功能描述：检测密钥令牌的有效性。

请求 URL：http://{{localhost}}/kapi/oauth2/verifyToken

调用方式：HTTP调用

请求方式：POST

请求类型：Content-Type:application/json

调用频率：1分钟30次

token有效期：2小时

请求Body参数：

请求参数示例：

{
  "client_id": "thirdappunittest_003",
  "token_type_hint": "access_token",
    "token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9peGdobmxERWluY1FpZDc2R2pjUDcyYlg0UTNwNDhpczZXM01NYTlsTDVhNEU2TFRkT0ZIWTlybUl5SDdvQUJ1ZGFSaGtWU0hGNlNRRTBjMjZ6MkxxQWRjbkNpTzBnd1ZzMW9P",
  "nonce": "1234",
  "timestamp": "2023-09-15 16:14:00",
  "accountId": "1331204445995794432"
}

返回参数：

返回参数示例：

{
    "data": {
    "expires_in": "7133040",
    "active": true,
    "scope": "API"
    },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明：

3.3 refreshToken

功能描述：当第三方应用通过 getToken接口获取了请求令牌后，可以使用返回参数中的刷新令牌（refresh_token），通过该接口刷新access_token的有效期。

请求 URL：http://{{localhost}}/kapi/oauth2/refreshToken

调用方式：HTTP调用

请求方式：POST

请求类型：Content-Type:application/json

调用频率：1分钟30次

token有效期：2小时

请求Body参数：

请求参数示例：

{
    "client_id": "thirdappunittest_003",
    "grant_type": "refresh_token",
    "refresh_token": "df591867-fb0d-4375-9e77-98ea276f59c0",
    "accountId": "1355633519610561536",
    "nonce": "123",
    "timestamp": "2023-09-08 11:47:00"
}

返回参数：

返回参数示例：

{
    "data": {
    "access_token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9zbmtvenFOb1hJcFpOdVhFY09aZTloVGliZjBIUTBuSlgyY2x0Uk95YTZkOTUxMjE0T0xQWVc4dldsU1Q4MjBqUDdqZjk5VmZSRzM5NlVlOTJRWWVIN1hSZTdINmYyN3pKSDVQ",
    "token_type": "Bearer",
    "refresh_token": "d367106c-de46-4fc4-9e1a-59cbcfc430d2",
    "scope": "API",
    "expires_in": "7199977",
    "id_token":"OPENAPIAUTH_ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5Sm1hV1FpT2lJeE16UTJOamN6T1NJc0luTjFZaUk2SW10a2FuZDBJaXdpWm5Cb2IyNWxJam9pTVRjeU9UazVPVGs1T1RraUxDSmxhV1FpT2lJeE1UUTNOVFl4TnlJc0ltWjBjblZsYm1GdFpTSTZJa2xGVWxBaUxDSm1iM0puYVdRaU9pSXhJaXdpWm1WdFlXbHNJam9pYVdWeWNFQnJhVzVuWkdWbExtTnZiU0lzSW1semN5STZJbXRrSWl3aWRYTmxjbWxrSWpvaU1UTTBOalkzTXpraUxDSm1ZbWw2Y0dGeWRHNWxjbWxrSWpvaU1DSXNJbVpzWVhOMGJHOW5hVzVwY0NJNklqRTNNaTR5TUM0eE5DNDJOeUlzSW1acGMyRmpkR2wyWldRaU9pSXhJaXdpWm05d1pXNXBaQ0k2SWpWaE1tUmxabU5pWlRSaU1EazFOMlpoTURobU9HTTNNaUlzSW1ac1lYTjBiRzluYVc1MGFXMWxJam9pTWpBeU15MHdPQzB5T1NBd01Eb3dNRG93TUM0d0lpd2labVZ1WVdKc1pTSTZJakVpTENKbWRXbGtJam9pTVRNME5qWTNNemtpTENKMWMyVnlWSGx3WlNJNklqRWlMQ0psZUhBaU9qRTJPVFEzTlRBek56SXNJbWxoZENJNk1UWTVORGMwTXpFM01pd2labWx6Y21WbmFYTjBaV1FpT2lJeElpd2labkJ6ZDNOMGNtRjBaV2Q1YVdRaU9pSTNOakk1TnpjM09UVTNOekl3TURVek56WWlMQ0oxYzJWeWIzQmxibWxrSWpvaU5XRXlaR1ZtWTJKbE5HSXdPVFUzWm1Fd09HWTRZemN5SWl3aWRYTmxjbTVoYldVaU9pSkpSVkpRSW4wLlc2S2ZRcE1nbUN6SzI1YnN0YUV1ZGoyNm1BMEdzZjdMR1FueU15NkgydEk=",
    "id_token_expires_in": "7199977",
    "language": null
        },
    "errorCode": "0",
    "message": "",
    "status": true
}

错误码说明：

3.4 withdrawToken

功能描述：撤回密钥令牌。

请求 URL：http://{{localhost}}/kapi/oauth2/withdrawToken

调用方式：HTTP调用

请求方式：POST

请求类型：Content-Type:application/json

调用频率：1分钟30次

token有效期：2小时

请求Body参数：

请求参数示例：

{
    "client_id": "thirdappunittest_003",
    "client_secret": "Abcdrty@1234567890#@2",
    "token_type_hint": "access_token",
    "token":"OPENAPIAUTH_MTMzMTIwNDQ0NTk5NTc5NDQzMl9peGdobmxERWluY1FpZDc2R2pjUDcyYlg0UTNwNDhpczZXM01NYTlsTDVhNEU2TFRkT0ZIWTlybUl5SDdvQUJ1ZGFSaGtWU0hGNlNRRTBjMjZ6MkxxQWRjbkNpTzBnd1ZzMW9P",
    "nonce": "12345",
    "timestamp": "2023-09-15 16:29:00",
    "accountId": "1331204445995794432"
}

返回参数：

返回参数示例：

{
    "data": true,
    "errorCode": "0",
    "message": "true",
    "status": true
}

错误码说明：

亮点价值

亮点一：规范易用

最新Token认证方式采用通用的参数命名，使接口更加规范，简化请求流程，同时提高了易用性。

亮点二：安全可信

引入随机数、时间戳、限流、黑白名单检查以及信息脱敏等措施，有效提升整体安全性，确保数据和令牌的安全传输。

划重点

苍穹V6.0 OpenAPI推出新功能“增强型Token认证”，有利于更好地管理API请求令牌，随时获取、刷新、撤回令牌和验证令牌有效性，并提升了Token全生命周期的安全性。使用时应注意：

• 获取token前必须在OpenAPI应用注册第三方应用，获取对应系统的client_id（系统编码）和client_secret（AccessToken认证密钥）信息；

• 新增的第三方应用中AccessToken认证策略卡片默认开启了“增强型Token认证”，若关闭开关，则仍可使用历史方式通过/api/login.do接口，获取access_token。

• 获取token时必须传入苍穹用户名username，不支持手机号或邮箱。