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.
| Authorization credential | Scenario | How to obtain |
|---|
| User access token | Apps that require sign-in user authorization. | Obtain user token |
| Internal app access token | Internal apps calling Server APIs to access app resources. | Obtain the access token of an internal app |
| Third-party enterprise app access token | Third-party enterprise apps or custom apps calling Server APIs to access app resources. | Obtain the access token of an organization that has authorized a third-party app |
| Third-party enterprise app suiteAccessToken | Obtain information about a third-party enterprise app. | Obtain the suiteAccessToken of a third-party enterprise app |
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:
GET https://api.dingtalk.io/v1.0/me/ HTTP/1.1
Host: api.dingtalk.io
Authorization: Bearer EwAoA8lxxxx=
Considerations
| Consideration | Description |
|---|
| 🔐 Client Secret leakage risk | Never print the Secret in frontend code, on the client-side, or in logs. |
| 🕒 Access token validity | Valid for 7,200 seconds by default. Implement an automatic refresh mechanism. |
| 🧩 Access token types supported by an API | Always check the specific API documentation to confirm. Do not mix token types. |
