授权套件SDK

更新于 2026-07-02本文介绍了如何使用钉钉统一授权套件SDK。

版本要求

钉钉统一授权套件SDK要求，钉钉版本需要在6.3.35及以上。低版本需提示用户升级客户端，你可以通过以下方式判断钉钉版本。

import { getENV, } from 'dingtalk-jsapi/lib/env';

import { compareVersion, } from 'dingtalk-jsapi/lib/sdk/sdkLib';

const { platform, version, appType, } \= getENV();

/**

* 判断当前app版本是否支持使用SDK

* @return {boolean}

function isAuthSDKSupport() {

return compareVersion(version, '6.3.35');

}

Enter to Rename, ⇧Enter to Preview

一、安装授权套件SDK

执行以下命令，下载安装SDK（dingtalk-design-libs需要版本在0.1.0及以上）。

1

npm install dingtalk-design-libs --save

Enter to Rename, ⇧Enter to Preview
下载完成后，直接在代码中导入即可。

1

import { openAuth } from 'dingtalk-design-libs/biz/openAuth';

Enter to Rename, ⇧Enter to Preview

二、应用授权接入

说明

一旦用户明确同意过授权，其授权关系会记录在后台，直到用户主动取消授权。

可以通过以下步骤使用钉钉统一授权套件引导用户授权相关信息。

引入钉钉统一授权套件SDK。

1

import { openAuth } from 'dingtalk-design-libs/biz/openAuth';

Enter to Rename, ⇧Enter to Preview
在需要用户授权时直接调用openAuth即可，请求示例如下：

1

2

3

4

5

6

7

8

9

openAuth({

  clientId:'dingwlanwxxx', // 应用ID(唯一标识)

  corpId:'', // 当前组织的corpId

  rpcScope:'Calendar.Event.Write,Calendar.Event.Read,Contact.User.Read',

  fieldScope:'Contact.User.mobile',

  type:0 // 0 表示授权个人信息；1 标识授权组织信息

}).then((res)=>{

// 处理返回数据

})

Enter to Rename, ⇧Enter to Preview

请求参数

参数	类型	是否必须	示例值	描述
clientId	string	是	f1dLkxxx	应用ID：

企业内部应用或第三方企业应用使用Client ID/Client Secret。
第三方个人应用使用App ID。
定制应用使用CustomKey。 | | corpId | string | 是 | ding123xxxx | 当前组织的corpId。
企业内部应用，填写当前应用所在的企业CorpId。
第三方企业应用，填写当前应用所在授权企业的CorpId。
第三方个人应用，填写当前个人应用所在的企业CorpId。 | | rpcScope | string | 否 | Contact.User.Read | 接口scope列表。

说明

多个scope使用英文逗号分隔。
rpcScope与fieldScope至少传一项。 | | fieldScope | string | 否 | Contact.User.mobile | 字段scope列表。

说明

多个scope使用英文逗号分隔。

0：申请个人授权
1：申请组织授权 | | from | string | 否 | alicloud | 请求来源。

说明

由调用方设置的位置标识，可自定义。 |

三、响应信息

返回示例如下：

授权完成

1

2

3

4

5

6

{

status: 'ok',

result: {

authCode:'xxxxxxx' // 如果是组织授权（type=1），则不返回该值

}

}

Enter to Rename, ⇧Enter to Preview
拒绝授权

1

2

3

4

{

status: 'cancel',

result: null

}

Enter to Rename, ⇧Enter to Preview
向管理员发送了授权申请，等待授权（只在组织授权场景下出现）

1

2

3

4

{

status: 'toAdmin',

result: null

}

Enter to Rename, ⇧Enter to Preview
授权异常

1

2

3

4

{

status: 'failed',

result: null

}

Enter to Rename, ⇧Enter to Preview

返回参数

字段名	类型	示例值	描述
status	string	ok	授权结果：

ok：授权成功
toAdmin：向管理员发送授权申请，等待授权
failed：授权异常
cancel：主动取消授权 | | result | Object | | 返回结果。 | | result.authCode | string | mrtjjwdmxxx | 个人临时授权码。

说明

当type=0时，授权成功会返回。 |

错误码

参数错误

错误码code	错误原因
400001	空请求。
400006	clientId参数必填。
400007	corpId参数必填。
400008	uid为空，请联系钉钉。

权限点相关错误

错误码code	错误原因
500201	权限点code错误。
500202	rpcScope参数需要填写rpc类型的权限点。
500203	fieldScope参数需要填写field类型的权限点。
500204	组织授权需要填写组织类型的权限点。
500205	个人授权需要填写个人类型的权限点

应用相关错误

错误码code	错误原因
500101	应用不存在。
500102	应用未添加任何权限点。
500103	获取应用信息失败。
500104	应用未添加该权限点，请在开发者后台添加。
500105	获取应用供应商组织信息失败。

授权相关错误

错误码code	错误原因
500401	获取授权人角色失败。
500402	非当前组织管理员。
500403	企业未开通授权此应用。
500404	更新授权记录失败。

四、取消授权（第三方个人应用）

打开取消授权页面的方式和打开授权页面方式一致，只有path值不同，示例代码如下：

openAuthMiniApp({

path:'pages/cancel/index',

extraData:{

clientId:'xxxxxx',

ext:'{}',

from:'' // 'aliCloud'

}

})

Enter to Rename, ⇧Enter to Preview