Skip to main content
Before calling the DingTalk OpenAPI, an app must obtain an access token from the DingTalk Open Platform. This token contains the app’s identity information and its access permissions for DingTalk resources, and serves as the required authentication credential for API calls.

​
Background

To help developers clearly understand the identity authentication mechanisms in different scenarios, this document provides a systematic introduction to the four types of access tokens supported by the DingTalk Open Platform, their applicable subjects, permission scopes, and usage methods. It also provides complete operation guidelines and key considerations to ensure that developers can correctly and efficiently complete preparations for API calls.

​
Permission overview

The DingTalk Open Platform uses two permission models to manage app access to resources, balancing security and flexibility:
Regardless of which permission type is used to call the DingTalk OpenAPI, you must first obtain the access token for the corresponding permission type.

​
Type 1: User identity access credential

  • Definition: User identity access credential (delegated permissions). The app requires user authorization to call the DingTalk OpenAPI on behalf of the signed-in user to operate on resources.
  • Characteristics:
    • The user must actively grant authorization to allow the app to access their personal data or perform actions on their behalf.
    • When calling the API, the user’s access token is used, and the operation results are limited by the user’s permissions.
    • Applicable to scenarios involving user private data, such as reading personal events or personal mobile numbers.

​
Type 2: App identity access credential

  • Definition: App identity access credential (application permissions). Suitable for apps that do not require user sign-in. When the app is installed, the admin can grant permissions in advance.
  • Characteristics:
    • The app can call the API independently of user identity and directly access organization-level resources.
    • Uses the access token of an internal app or a third-party app.
    • Applicable to backend tasks, batch processing, automated operations, and similar scenarios.

​
Access token

The access token is issued by the DingTalk Open Platform to verify the caller’s identity and ensure that the caller has the permissions required to perform the intended actions. The DingTalk Open Platform currently provides the following four types of access tokens, corresponding to different application scenarios and permission tiers:
Calling the same API with different access tokens may return different data. For details, refer to the specific API documentation.

​
How to use the access token

To call the DingTalk OpenAPI, attach the access token as a Bearer token in the Authorization header of the HTTP request. For example:
For complete operations, refer to:

​
Considerations