认证授权

服务端 API 更新于 2026-08-28 阅读 11

获取人员免登授权码

接口说明：在第三方应用需要识别端上人员身份的时候，发起认证授权流程，成功时应用可以通过redirect_uri接口获取到授权Code，按照OAuth2标准的建议，Code 5分钟有效且只能使用一次。请求方式：GET (HTTPS)请求地址： https://passport-example.domain/oauth2/authorize?appid=APPID&response_type=code&scope=SCOPE&state=STATE&redirect_uri=REDIRECT_URI

注：请求地址中的 "passport-example.domain" 指的是授权页服务对应的域名，不同部署环境的域名不同，蓝信云平台地址参考应用接入指南, 其他部署环境请联系客服获取。

query参数说明：

参数	必须	说明
appid	是	应用ID
response_type	是	必须为"code"
scope	是	应用授权列表，多个授权请求需要以 scope="scope1,scope2" 形式。
state	是	发起请求的时候携带的随机值，和该重定向请求唯一对应。同时，也能按 OAUTH2 协议防止 CSRF 攻击
redirect_uri	是	需要做 urlencode 处理。其中包含的域名需要在应用可信域名配置列表里

当前支持的scope类型：|scope|说明 | |------------|--------------------| | basic_userinfor | 基本人员信息。如需要人员授权就能获取。 |

出错处理:

成功时会302重定向到请求的 redirect_uri，并附带code，state等参数，即REDIRECT_URI.(?|&)code=CODE&state=STATE ; 例如：https://app.domain?code=4d32b46d-3e88-44b2-9c7a-903ac638fcfb&state=572ca2d8-4383-11eb-96e3-0242ac11e605

对应可能的错误码说明：接口错误码调用示例： 注: 测试时需要替换域名和appid两个字段为你的测试环境对应的域名和appid, 将http://localhost:8080配置到蓝信开发者中心应用的可信域名：

https://passport-test.test.com/oauth2/authorize?appid=3064064-123456&response_type=code&scope=basic_userinfor&state=3da9d9f1-6756-11ea-8b95-0242ac115010&redirect_uri=http://localhost:8080

获取人员访问TOKEN

接口说明：OAuth2 授权流程，通过 OAuth2 授权码获取人员身份访问USER_TOKEN请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/usertoken/create?app_token=APP_TOKEN&grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URIquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问APP_TOKEN
grant_type	是	使用固定值 “authorization_code”
code	是	调用接口获得获取人员免登录授权码
redirect_uri	否	非必填字段

返回参数字段说明：|参数|类型|描述 | |------------|----------|--------------------------------------------------------------------------------------| | userToken | string | 新分配的人员 TOKEN | | expiresIn | int | 有效期（7200秒），建议应用根据过期时间缓存userToken | | scope | string | 当人员选择的授权SCOPE 和请求的 SCOPE 不一致的时候，该字段出现。其表示最终人员选择的授权列表。 | | state | string | 和请求授权的参数STATE 一致。 | | staffId | string | 人员OpenId。如果应用已经缓存了人员信息，获取staffId后无须再调用获取人员基本信息接口。 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "userToken":"67566-9870-9865-4321",
    "expiresIn":7200,
    "scope": "scope1,scope2",
    "state": "STATE0x8765",
    "staffId": "524288-abcedfghigklmn"
  }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取人员访问TOKEN V2

接口说明：OAuth2 授权流程，通过 OAuth2 授权码获取人员身份访问USER_TOKEN，该V2版接口支持返回REFRESH_TOKEN请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v2/user_token/create?app_token=APP_TOKEN&grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URIquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问APP_TOKEN
grant_type	是	使用固定值 “authorization_code”
code	是	调用接口获得获取人员免登录授权码
redirect_uri	否	非必填字段

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "userToken":"db501ca9-fe6c-11ec-8747-be04fc88dec5",
    "expiresIn":7200,
    "refreshToken":"1cf4a0b2-fe6d-11ec-8b9d-62bb1295b923",
    "refreshExpiresIn":2592000,
    "scope": "scope1,scope2",
    "state": "fa8a0a63-fe6c-11ec-9438-162619e741e0",
    "staffId": "524288-abcedfghigklmn"
  }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

刷新人员访问TOKEN

接口说明：使用refresh_token刷新user_token，如果refresh_token已过期，需要重新发起OAuth授权流程获取新的refresh_token请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/refresh_token/create?app_token=APP_TOKEN&grant_type=refresh_token&refresh_token=REFRESH_TOKEN&scope=SCOPEquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问APP_TOKEN
grant_type	是	使用固定值 “refresh_token”
refresh_token	是	调用接口获得获取人员访问TOKEN V2
scope	否	应用于scope缩减情况，refresh_token接口中的scope不能超出原始的user_token所获取的授权范围（只能减少不能增加）

返回参数字段说明：|参数|类型| 描述 | |------------|---------|---------------------------------------------------------------------------------------| | userToken | string | 新分配的人员 TOKEN | | expiresIn | int | 有效期（7200秒），建议应用根据过期时间缓存userToken | | refreshToken | string | 在总有效期不变的情况下，老的refresh_token会被一个新的refresh_token取代，请求参数中的老refresh_token会失效，下次再次刷新user_token时需要使用返回的新的refresh_token。这样做的目的是保证安全性。 | | refreshExpiresIn | int | refresh_token有效期（秒），此时返回的refresh_token有效期是请求参数中refresh_token 有效期的剩余时间。换句话说，使用code获取的原始refresh_token有效期是30天，中间换取的多个新的refresh_token的有效期是原始refresh_token有效期的剩余时间，refresh_token虽然更新了，但总的有效时间并没有变化。refresh_token到期后需要重新发起OAuth授权获取新的refresh_token。这样做的目的是保证安全性。 | | scope | string | 当用户选择的授权SCOPE 和请求的 SCOPE 不一致的时候，该字段出现。其表示最终用户选择的授权列表。 | | state | string | 和请求授权的参数STATE 一致。 | | staffId | string | 人员OpenId。如果应用已经缓存了人员信息，获取staffId后无须再调用获取人员基本信息接口。 |

返回数据示例：

业务正常返回：

{
  "errCode":0 ,
  "errMsg":"ok",
  "data":{
    "userToken":"e3474e95-fe6c-11ec-979d-fa55fbd6fc61",
    "expiresIn":7200,
    "refreshToken":"db9c959f-fe6c-11ec-8747-be04fc88dec5",
    "refreshExpiresIn":1792360,     
    "scope":"scope1,scope2",
    "state":"STATE0x8765",
    "staffId":"524-ADAFSFD87F"
  }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取应用访问TOKEN

接口说明：使用AppId，AppSecret，创建应用访问APP_TOKEN请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/apptoken/create?grant_type=client_credential&appid=APPID&secret=SECRETquery参数说明：

参数	必须	说明
grant_type	是	可赋值为："client_credential"
appid	是	应用ID, 创建应用时取得
secret	是	应用对应的AppSecret，创建应用时取得

返回参数字段说明：|参数|类型| 描述 | |------------|---------|-----------| | appToken | string | 应用访问APP_TOKEN | | expiresIn | int | TOKEN 有效期（7200秒），建议应用根据过期时间缓存appToken, 单次获取，多次使用 |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
         "appToken": "APP_TOKEN",
         "expiresIn": 7200
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取人员基本信息

接口说明：根据人员token 获取当前端上登录人员信息请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/users/fetch?app_token=APP_TOKEN&user_token=USER_TOKENquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问TOKEN
user_token	是	调用接口获得获取人员访问TOKEN

返回参数字段说明：|参数|类型|描述 | |-------------------|---------|--------------| | staffId | string | 人员ID | | name | string | 人员名称 | | orgId | string | 组织ID | | orgName | string | 组织名称 | | avatarId | string | 头像ID | | avatarUrl | string | 头像地址 | | mobilePhone | json obj | 手机号 | | mobilePhone.countryCode | string | 国家码 | | mobilePhone.number | string | 手机号| | email | string | 邮箱地址 | | employeeNumber | string | 员工号 | | LoginName | string | 登录用户名 | | externalId | string | 外部数据源人员唯一ID | | department | obj array | 所在分支信息 | | department.id | string | 所在分支ID | | department.name | string | 所在分支名称 |

返回数据示例：

业务正常返回：


{
     "errCode": 0,
     "errMsg": "ok",
     "data":{
         "staffId": "788-59",
         "name": "张三",
         "orgId": "788",
         "orgname":"组织名称",
         "avatarUrl": "http://路径",
         "avatarId":"788-3456",
         "mobilePhone": {
            "countryCode": "86",
            "number": "12345678902"
         },
         "email": "email@test.com",
         "employeeNumber": "A00001",
         "loginName": "login001",
         "externalId": "zhangsan01",
         "department": [
              {
                  "id": "524288-3145728",            
                  "name": "lanxin-core"
              }
         ]
     }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

获取JSAPI访问TOKEN

接口说明： 创建JSAPI访问JS_API_TOKEN，该JS_API_TOKEN用于生成JSAPI签名参数，用于JSAPI接口的身份验证。特别说明：该JS_API_TOKEN 2小时有效，系统只保存单一JS_API_TOKEN，换取新TOKEN后老TOKEN会立即失效，所以应用服务端必须按接口返回的TOKEN有效时间对该JS_API_TOKEN进行全局缓存，避免并发场景下JS验签失败

请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/jsapitoken/create?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问TOKEN
user_token	否	非必填字段

返回参数字段说明：|参数 |类型| 描述 | |-------------|-------|-----------| | jsApiToken | string | JSAPI 访问TOKEN | | expiresIn | int | TOKEN 有效期（7200秒），建议应用根据过期时间缓存jsApiToken |

返回数据示例：

业务正常返回：

{
    "errCode": 0,
    "errMsg": "ok",
    "data": {
         "jsApiToken": "JS_API_TOKEN",
         "expiresIn": 7200
    }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：### 接口错误码签名实例:>具体签名过程如下：

signatureStr := fmt.Sprintf("js_api_token=%v&noncestr=%v&timestamp=%v&url=%v", token, nonce, timestamp, url)
signature := sha1(signatureStr)

测试案例：

// js token
token := "31a4a1aa-cffc-4aca-9ef6-0497edf7fbed"
// 随机字符串
nonce := "e30fdeda-f13c-4cca-a0a6-94b507d2b260"
// 时间戳
timestamp := "1569275968"
// url
url := "http://www.test.com/index.html?open_type=webview/"

签名原始字符串生成：signatureStr : js_api_token=31a4a1aa-cffc-4aca-9ef6-0497edf7fbed&noncestr=e30fdeda-f13c-4cca-a0a6-94b507d2b260&timestamp=1569275968&url=http://www.test.com/index.html?open_type=webview/

签名结果：signature : 2e3efe2bf4482494b4f7af07817656c72c70d79a

签名算法详细说明参考：JSSDK签名认证说明

身份识别码获取人员信息

接口说明：根据蓝信人员身份识别码获取蓝信组织人员ID，详细说明参考身份识别码使用说明请求方式：GET (HTTPS)请求地址：https://apigw-example.domain/v1/qrcode/:qrcode/staff/fetch?app_token=APP_TOKENquery参数说明：

参数	必须	说明
app_token	是	调用接口获得获取应用访问TOKEN

param参数说明：

参数	必须	说明
qrcode	是	人员身份识别码，读码器读取人员身份识别后获取。身份识别码打开方式：蓝信客户端（移动端）-->我的-->身份识别码

返回参数字段说明：|参数|类型|描述 | |-------------------|---------|--------------| | staffId | string | 人员ID |

返回数据示例：

业务正常返回：


{
     "errCode": 0,
     "errMsg": "ok",
     "data":{
         "staffId": "524288-xxxxxxxxx"
     }
}

业务异常返回：

{
    "errCode": 错误码 ,
    "errMsg": 对应的统一错误码描述
}

对应可能的错误码说明：

接口错误码

💬 即时通讯

🤝 业务协同

📦 AI产品

📦 其他产品

openplatform

认证授权

获取人员免登授权码

获取人员访问TOKEN

获取人员访问TOKEN V2

刷新人员访问TOKEN

获取应用访问TOKEN

获取人员基本信息

获取JSAPI访问TOKEN

身份识别码获取人员信息