Skip to main content
Before calling DingTalk server-side APIs, add the required API call permissions. After an app is created, the system grants Authentication and Message notification API permissions by default. We encourage apps to use as many APIs as possible to achieve full interoperability with DingTalk’s core capabilities.

​
Applicable scope

  • Internal app: An app developed by an organization for its own internal use. Suitable for internal system integration scenarios.
  • Third-party enterprise app: A service app developed by an ISV (Independent Software Vendor) for installation and use by multiple enterprise customers.
  • Third-party personal app: An app developed by solution providers for personal users on DingTalk.
Permission request procedures, approval processes, and API availability may vary by app type. Refer to the instructions that apply to your app type.

​
Overview

Before calling DingTalk server-side APIs, add the corresponding API call permissions to the app. After an app is created, the system grants certain basic permissions by default. Request the required API permissions based on your business needs to achieve deep integration with DingTalk’s core capabilities. API permissions are granted at the app level, and permissions are independent across apps. Even if multiple apps within the same organization need to call the same API, the permission must be requested separately for each app. For example, if your organization has two apps, A and B, and app A already has the Contacts read permission, app B must still request the Contacts permission separately to access Contacts data. The procedure is the same as for app A.
Not all APIs can be enabled directly. Some APIs are non-public capabilities and require approval before use. Other premium APIs may involve fees or specific qualification requirements. Refer to the scope description in each API document for details.

​
Prerequisites

Before configuring API permissions, ensure the following conditions are met:
  1. The app type is Internal app, Third-party enterprise app, or Third-party personal app, and the app has been created in the Developer Console.
  2. The current account has management permissions for the app (typically an Organization Admin or app owner).
  3. The organization has completed authentication (some APIs require real-name organization authentication before they can be requested).
  4. The AppKey and AppSecret of the app have been obtained and configured properly for API authentication.

​
Add standard API call permissions

This procedure applies to most public server-side APIs and can be requested directly through the Developer Console. Procedure:
  1. In the API document, copy the permission scope from the Permissions section of the target API.
  2. Sign in to the Developer Console.
  3. On the App Development page, click the target app to enter the app details page.
  4. On the app details page, click Manage permissions, search for the copied permission scope, and click Request permission.

​
Add special API call permissions

For non-public, sensitive, or industry-specific APIs, manual approval by DingTalk is required before they can be enabled. Procedure:
  1. In the API document, copy the permission scope from the Permissions section of the target API.
  2. Sign in to the Developer Console as an Admin.
  3. On the App Development page, click the target app to enter the app details page.
  4. Click Manage permissions, select the special API to add, and click Request permission.
  5. Enter the request description and click Request. Tips
    • API permission requests are reviewed by the DingTalk team responsible for the corresponding API. Approval is typically completed within one business day. After approval, the status changes to Enabled.
    • If the request is declined, locate the permission entry in the Requests list, hover over the Review Failed tag to view the specific reason, and resubmit after making improvements based on the feedback.

​
Troubleshoot permission errors

This solution currently applies only to calls made to the new server-side APIs.
When a new API call returns a 403 error, the response body contains detailed information about the missing permissions: 
{
  "Code": "Forbidden.AccessDenied.AccessTokenPermissionDenied",
  "StatusCode": 403,
  "Message": "code: 403, no permission to call this API request id: 8197EFxxxx59D33E58",
  "Data": "{\"AccessDeniedDetail\":{\"requiredScopes\":[\"Contact.Org.Read\"]},\"Code\":\"Forbidden.AccessDenied.AccessTokenPermissionDenied\",\"HostId\":\"dingtalk-inner.aliyuncs.com\",
            \"Message\":\"no permission to call this API\",\"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"
    ]
  }
}
When an app returns the error “no permission to call this API”, follow these steps:
  1. Extract the value of the requiredScopes field within AccessDeniedDetail in the error response. This is the permission scope code required by the target API.
  2. On the Manage permissions page of the current app, search for the permission scope code and request the corresponding API permission.

​
Important