授权套件-概述.md 6.9 KB
概述
更新于 2026-07-02本文介绍了钉钉统一授权套件的基本概念、使用场景及关键权限机制，帮助开发者正确配置和调用涉及用户敏感信息的API接口。通过本文档，开发者可了解授权流程、权限类型、适用对象以及如何处理未授权导致的调用失败问题。
简介
为保障用户数据安全，当应用需要调用涉及个人信息的API时（如个人手机号、邮箱、头像等），必须经过用户或企业管理员的明确授权。未获得相应授权前，相关接口将无法访问敏感信息，或返回错误码提示权限不足。
本文适用于开发第三方企业应用和第三方个人小程序的开发者，重点说明以下内容：
如何判断某项信息是否需要单独申请字段权限；
用户与管理员在授权过程中的角色差异；
开发者如何通过前端SDK触发授权弹窗，并监听授权状态变化；
授权失败或未授权情况下的错误处理方式。
个人信息授权
在用户使用应用过程中，若涉及获取其个人信息：
若用户已授权对应权限，应用可直接调用相关API。
若用户尚未授权或曾拒绝授权，则会触发授权弹窗提示，用户需主动点击“同意”后方可完成授权并正常调用接口。
授权弹窗界面，如下图所示：
第三方企业应用增量授权
当第三方企业应用在后续迭代中新增调用其他钉钉API时，若该接口涉及受保护资源，需由授权企业手动完成权限授予操作，此过程称为“增量授权”。
授权企业管理员授权
若当前操作者为企业管理员，可直接进入授权页面进行确认操作。
管理员授权页面样例，如下图所示：
授权企业非管理员需要选择管理员授权
若当前操作者为非管理员成员，则需选择指定管理员进行代为授权：
选定后，该管理员会收到一条消息卡片通知，提示其进行授权审批，样例如下：
第三方个人应用使用场景
个人信息授权
本场景适用于开发第三方个人小程序，且希望获取用户的以下信息：
用户个人手机号
钉钉头像URL
个人邮箱等通讯录相关信息
说明
对于企业内部应用，可通过通讯录相关接口直接获取头像URL、邮箱等信息，无需接入钉钉统一授权套件。
个人权限scope列表
目前仅支持以下两类权限类型，分别对应不同的授权粒度与适用范围。
| 权限信息 | 接口/字段
列表 | 授权的信息示例 | scope(权限点code) | 数据类型 | 权限类型 | |------------|-------------------------|--------------------|---------------------|------|------------------| | 通讯录个人信息读权限 | 接口：获取用户通讯录个人信息 | 用户个人的钉钉昵称、头像、个人邮箱等 | Contact.User.Read | 个人信息 | 接口权限
rpcScope | | 个人手机号信息 | 字段：获取用户通讯录个人信息-mobile字段 | 用户的个人手机号 | Contact.User.mobile | 个人信息 | 字段权限
fieldScope |
术语说明：
rpcScope（接口权限）：表示对某个API接口的整体调用权限。申请此权限后，应用可调用该接口，但仅能获取其中无需额外授权的公共字段。
fieldScope（字段权限）：表示对特定敏感字段的访问权限。即使拥有接口调用权限，若未单独申请字段权限（如手机号），仍无法获取该字段数据。
个人信息权限申请示例
示例一：获取用户个人手机号
第三方企业应用希望调用获取用户通讯录个人信息接口，获取用户个人手机号信息，需要申请哪些权限？
说明
个人手机号信息需要单独申请字段权限，因此开发者需要同时申请接口权限和字段权限。
需要申请接口权限-获取用户通讯录个人信息
需要申请字段权限-个人手机号信息权限
如下图所示，对应开发者后台需添加的权限项：
示例二：获取用户个人邮箱与钉钉头像
第三方企业应用希望调用获取用户通讯录个人信息接口，获取用户个人邮箱、钉钉头像等信息，需要申请哪些权限？
说明
个人邮箱、钉钉头像等信息不涉及独立字段权限，仅需申请接口权限即可。
需要申请接口权限-获取用户通讯录个人信息
如下图所示，对应开发者后台需配置的权限项：
用户未授权，应用调用API报错
在调用需授权才能访问的服务端API时，如果用户未完成授权，系统会返回错误码60011，或响应中缺失期望的某些字段数据。
常见错误表现：
返回错误码：
60011调用结果中
mobile字段为空或不存在
解决方案：
确认已在开发者后台正确添加对应权限（包括接口权限和字段权限）。
检查用户是否已完成授权流程，必要时重新触发授权弹窗。
第三方企业应用使用场景
个人信息授权
本场景适用于开发第三方企业应用，且希望获取企业内用户以下信息：
用户个人邮箱
钉钉头像URL
其他基于统一授权保护的个人信息
此类信息的获取需遵循钉钉统一授权机制，确保企业在授权范围内允许数据访问。
第三方企业应用增量授权
当第三方企业应用在后续产品迭代中需要接入新的钉钉API时，若该接口涉及受保护资源（如通讯录、日程、审批等），必须完成增量授权流程。