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