添加接口调用权限.md 6.2 KB
添加接口调用权限
更新于 2026-07-02调用钉钉服务端接口前，需要先添加所需接口的调用权限，应用创建后，系统默认添加身份验证和消息通知接口权限。鼓励应用使用尽可能多的接口，实现跟钉钉核心能力的全面互通。
适用对象
本文档适用于在钉钉开放平台开发的企业内部应用、第三方企业应用和第三方企业应用开发者。
企业内部应用：由企业自主开发并仅供本企业使用的应用，适用于组织内部系统集成场景。
第三方企业应用：由ISV（独立软件开发商）开发，供多个企业客户安装使用的服务型应用。
第三方个人应用：产品方案商开发者开发，提供给钉钉上个人用户使用的应用。
不同应用类型在权限申请、审批流程及接口可用性方面可能存在差异，请根据实际应用类型参考对应操作指引。
功能概述
调用钉钉服务端接口前，必须为应用添加对应的接口调用权限。应用创建后，系统默认会授予部分基础权限。建议根据业务需求合理申请所需接口权限，实现与钉钉核心能力的深度集成。
接口权限以应用为维度进行授权，各应用之间权限相互独立。即使同一企业的多个应用需要调用相同接口，也需分别在各自应用中单独申请。
例如：企业内同时拥有 A、B 两个应用，即使应用 A 已具备通讯录读取权限，应用 B 若要访问通讯录数据，仍需单独申请“通讯录”相关权限，操作流程与应用 A 一致。
重要
并非所有接口均可直接开通。部分接口属于非公开开放能力，需提交审批并通过审核后方可使用；另有部分高级接口可能涉及付费或特定资质要求，请以具体接口文档中的使用范围说明为准。
前置条件
在进行接口权限配置前，请确保满足以下条件：
应用类型为企业内部应用、第三方企业应用或第三方个人应用，且已在开发者后台完成创建。
当前登录账号具备该应用的管理权限（通常为企业管理员或应用负责人）。
企业已完成认证（部分特殊接口需企业实名认证后方可申请）。
已获取并妥善配置应用的
AppKey和AppSecret，用于调用API的身份验证。
添加普通接口调用权限
适用于大多数公开开放的服务端API，可直接在开发者后台自助申请。
操作流程：
在接口文档中，复制目标接口文档中权限模块的权限点。
登录开发者后台，在应用开发页面，单击目标应用进入应用详情页面。
在应用详情页，单击权限管理，搜索复制的权限点，单击立即开通即可。
添加特殊接口调用权限
针对非公开开放的敏感或行业专用接口，需经过钉钉方人工审批后方可启用。
操作流程：
在接口文档中，复制目标接口文档中权限模块的权限点。
管理员登录开发者后台。
在应用开发页面，单击目标应用进入应用详情页面。
单击权限管理，选择需要添加的特殊接口，单击立即开通，填写申请说明，最后单击申请。
说明
接口调用权限申请会由对应接口的钉钉小二进行审批，审批一般会在一个工作日内完成，审批通过后状态变为已开通。
若申请被拒绝，可在申请栏中定位到该权限条目，将鼠标悬停于审核未通过标签上查看具体驳回原因，并根据反馈优化后重新提交。
无权限报错的解决办法
说明
此解决方法目前仅限于调用新版服务端API时适用。
当调用新版API返回 403 错误时，响应体中会包含详细的权限缺失信息：
{
"Code": "Forbidden.AccessDenied.AccessTokenPermissionDenied",
"StatusCode": 403,
"Message": "code: 403, 没有调用该接口的权限 request id: 8197EFxxxx59D33E58",
"Data": "{\"AccessDeniedDetail\":{\"requiredScopes\":[\"Contact.Org.Read\"]},\"Code\":\"Forbidden.AccessDenied.AccessTokenPermissionDenied\",\"HostId\":\"dingtalk-inner.aliyuncs.com\",
\"Message\":\"没有调用该接口的权限\",\"Recommend\":\"https://next.api.aliyun.com/troubleshoot?q=Forbidden.AccessDenied.AccessTokenPermissionDenied\\u0026product=dingtalk\",
\"RequestId\":\"8197Exxxx88C759D33E58\",\"statusCode\":403}",
"Stack": null,
"Description": "\u003cni\u003e",
"AccessDeniedDetail": {
"requiredScopes": [
"Contact.Org.Read"
]
}
}
应用调用接口时返回提示“没有调用该接口的权限”，解决步骤：
提取错误响应中
AccessDeniedDetail中的requiredScopes字段的值，即为目标接口所需的权限点 Code。在当前应用的权限管理页面，搜索该权限点Code后，申请开通对应接口权限。
重要
第三方企业应用在接入统一授权套件时，权限点Code作为的
rpcScope或fieldScope参数值。