Skip to main content

如何认证

danger

请务必将 access_token 进行缓存

系统对每个坐席获取 access_token 的频率限制为 24小时周期内128次，超过此频率将获取 access_token 失败。

概述​

使用 OAUTH2 协议进行认证，获取access_token后，后续所有的接口访问都需要带上此token。

字段说明​

字段说明
access_token后续所有的接口访问都需要带上此token
expires_inaccess_token有效时间，过期后将无法使用
token_typeBearar，固定值
scope权限范围（由中通天鸿用户中心分配）
client_id由中通天鸿用户中心分配
client_secret由中通天鸿用户中心分配
grant_type由中通天鸿用户中心分配
username格式为 `企业代码
password企业下用户工号对应的密码

坐席所属 access_token 获取​

推荐方式一：通过 authorization_code 方式获取access_token​

接口地址​

POST /oauth2/token

入参​

参数位置类型说明必填
Content-Typeheaderstringapplication/x-www-form-urlencoded 或 application/json是
client_idbodystring由中通天鸿用户中心分配是
client_secretbodystring由中通天鸿用户中心分配是
grant_typebodystring固定值：authorization_code是
codebodystring根据下述算法生成是
code 生成算法​

为避免歧义，code 生成规则如下：

  • 加密算法：aes-256-cfb
  • key：client_secret
  • iv：client_secret 前 16 位
  • 明文编码：UTF-8 JSON（单行，无多余空格）
  • 密文编码：base64
  • 最终格式：server:{base64_cipher}
第 1 步：确定加密参数​

假设分配的 client_id=client-6026123456、client_secret=B7iSSRkfP0ll9PvqsYQeNExPgSc7oKQd，则 iv=B7iSSRkfP0ll9Pvq。

第 2 步：组装明文数据​

明文 JSON 字段如下：

参数类型说明必填
user_idint坐席 id与 user_num 二选一
user_numstring坐席工号与 user_id 二选一
timestampint秒级时间戳；与标准时间误差不能超过 60 秒，否则请求会被拒绝是
scopestring[]授权所属权限否

示例明文：

{
  "user_num": "8001",
  "timestamp": 1770631591
}
第 3 步：加密并 Base64 编码​

将第 2 步明文转换为单行 JSON 后执行加密：

base64_encode(encrypt('{"user_num":"8001","timestamp":1770631591}', 'aes-256-cfb', 'B7iSSRkfP0ll9PvqsYQeNExPgSc7oKQd', 'B7iSSRkfP0ll9Pvq'))

按上述参数生成的密文为：+4WCGyLuSFq/5suYPqBlZiPNGnWODg7yXzkuJ6SrMVmr6BFQ。

第 4 步：拼接最终 code​

在第 3 步密文前拼接固定前缀 server:，得到最终 code：

server:+4WCGyLuSFq/5suYPqBlZiPNGnWODg7yXzkuJ6SrMVmr6BFQ

出参​

参数类型说明必填
access_tokenstringaccess_token是
expires_instring此 token 的过期时间，单位：秒是
token_typestring固定值：Bearer是
scopestring此 token 的所属权限是
refresh_tokenstringrefresh_token，一般无需关注否

举例​

curl --location --request POST 'https://account.icsoc.net/oauth2/token' \
--form 'client_id="client-421616126"' \
--form 'client_secret="SLnQJchkUmVP68X812345678"' \
--form 'grant_type="authorization_code"' \
--form 'code="server:+4WCGyLuSFq/5suYPqBlZiPNGnWODg7yXzkuJ6SrMVmr6BFQ"'

方式二：通过 password 方式获取access_token​

接口地址​

POST https://account.icsoc.net/oauth2/token

入参​

参数位置类型说明必填
Content-Typeheaderstringapplication/x-www-form-urlencoded 或 application/json是
client_idbodystring由中通天鸿用户中心分配是
client_secretbodystring由中通天鸿用户中心分配是
grant_typebodystring固定值：password是
usernamebodystring格式为 `企业代码用户工号，例如 6019100001
passwordbodystring企业下用户工号对应的密码是
scopebodystring权限范围（由中通天鸿用户中心分配）是

出参​

参数类型说明必填
access_tokenstring后续所有的接口访问都需要带上此token是
expires_instring有效时间，过期后将无法使用，单位：秒是
token_typestring固定值: Bearer是
scopestring权限范围（由中通天鸿用户中心分配）是

举例​

curl -X POST \
  https://account.icsoc.net/oauth2/token \
  -F client_id={client_id} \
  -F client_secret={client_secret} \
  -F grant_type=password \
  -F 'username={企业代码}|{工号}' \
  -F password={password}
  -F scope=openid

# 或者 application/json 格式

curl -X POST \
  https://account.icsoc.net/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "grant_type": "password",
    "username": "{企业代码}|{工号}",
    "password": "{password}",
    "scope": "openid"
  }'
{
    "access_token": "434233e4631417de4da122f4275bf76854004f68",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "default"
}

企业 access_token 获取​

danger

注意，此方式获取的 token 是企业级别的 access_token，适用于企业级别的接口访问，例如坐席管理等接口访问。

此类 token 没有坐席属性，不能通过此类 token 识别出具体坐席。

接口地址​

POST https://account.icsoc.net/oauth2/token

入参​

参数位置类型说明必填
Content-Typeheaderstringapplication/x-www-form-urlencoded 或 application/json是
client_idbodystring由中通天鸿用户中心分配是
client_secretbodystring由中通天鸿用户中心分配是
grant_typebodystring固定值：client_credentials是
scopebodystring权限范围（由中通天鸿用户中心分配）是

出参​

参数类型说明必填
access_tokenstring后续所有的接口访问都需要带上此token是
expires_instring有效时间，过期后将无法使用，单位：秒是
token_typestring固定值: Bearer是
scopestring权限范围（由中通天鸿用户中心分配）是

举例​

curl -X POST \
  https://account.icsoc.net/oauth2/token \
  -F client_id={client_id} \
  -F client_secret={client_secret} \
  -F grant_type=client_credentials \
  -F scope=openid

# 或者 application/json 格式

curl -X POST \
  https://account.icsoc.net/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "{client_id}",
    "client_secret": "{client_secret}",
    "grant_type": "client_credentials",
    "scope": "openid"
  }'
{
    "access_token": "434233",
    "expires_in": 86400,
    "token_type": "Bearer",
    "scope": "default"
}