获取用户token.md 5.8 KB
获取用户token新版SDK
更新于 2026-06-30通过此接口获取用户级别的访问令牌（access token），支持 OAuth 2.0 授权码模式和刷新令牌模式，适用于需要以用户身份调用钉钉开放平台 API 的第三方个人应用。
使用场景
该接口用于获取用户的accessToken，是实现用户身份认证的关键步骤。常见使用场景包括：
用户登录后，通过授权码（
code）换取有效的访问凭证。在
accessToken过期前，使用refreshToken自动续期，避免频繁重新授权。第三方企业应用集成钉钉统一登录体系，实现单点登录（SSO）。
企业应用在后台服务中代表用户调用受保护的 API 接口。
开发者应妥善管理accessToken的生命周期，建议在本地缓存并设置自动刷新机制，确保调用稳定性。
说明
在使用accessToken时，请注意：
accessToken的有效期为7200秒（2小时），有效期内重复获取将返回相同结果并自动续期；过期后获取会返回新的accessToken。每个应用的
accessToken相互独立，缓存时需按应用维度进行存储，防止混淆。
请求
| 基本信息 | 基本信息 |
|---|---|
| HTTP URL | https://api.dingtalk.com/v1.0/oauth2/userAccessToken |
| HTTP Method | POST |
| 支持的应用类型 | 企业内部应用第三方企业应用第三方个人应用 |
| 权限要求 | 获取钉钉开放接口用户访问凭证的基础权限 |
请求体
| 名称 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| clientId | String | 是 | dingxxx | 应用id。可使用扫码登录应用或者第三方个人小程序的appId。 |
企业内部应用传应用的AppKey
第三方企业应用传应用的SuiteKey
第三方个人应用传应用的AppId | | clientSecret | String | 是 | 1234 | 应用密钥。
企业内部应用传应用的AppSecret
第三方企业应用传应用的SuiteSecret
第三方个人应用传应用的AppSecret | | code | String | 否 | abcd | OAuth 2.0 临时授权码，第三方企业应用需要接入统一授权套件/获取登录用户的访问凭证，获取临时授权码authCode。 | | refreshToken | String | 否 | abcd | OAuth 2.0 刷新令牌，从上一次接口返回结果中获取。有效期为 30 天。 | | grantType | String | 是 | authorization_code | - 如果使用授权码换token：传
authorization_code，此时必须填写code参数。使用刷新 token 换新 token：传
refresh_token，此时必须填写refreshToken参数。 |
请求示例
curl
1
2
3
4
5
6
7
8
9
curl -X POST 'https://api.dingtalk.com/v1.0/oauth2/userAccessToken' \
-H 'Content-Type: application/json' \
-d '{
"clientId": "dingxxx",
"clientSecret": "1234",
"code": "abcd",
"refreshToken": "abcd",
"grantType": "authorization_code"
}'
Enter to Rename, ⇧Enter to Preview
Java
1
// This file is auto-generated, don't edit it. Thanks.
Enter to Rename, ⇧Enter to Preview
Python
1
# -*- coding: utf-8 -*-
Enter to Rename, ⇧Enter to Preview
PHP
1
<?php
Enter to Rename, ⇧Enter to Preview
Go
1
// This file is auto-generated, don't edit it. Thanks.
Enter to Rename, ⇧Enter to Preview
Node.js
1
// This file is auto-generated, don't edit it
Enter to Rename, ⇧Enter to Preview
C#
1
// This file is auto-generated, don't edit it. Thanks.
Enter to Rename, ⇧Enter to Preview
C++
1
// This file is auto-generated, don't edit it. Thanks.
Enter to Rename, ⇧Enter to Preview
响应
响应体
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| accessToken | String | abcd | 生成的accessToken，用于后续 API 调用的身份验证。 |
| refreshToken | String | abcd | 生成的refresh_token。可以使用此刷新token，定期的获取用户的accessToken |
| expireIn | Long | 7200 | 超时时间，单位秒。 |
| corpId | String | corpxxxx | 所选企业corpId。 |
响应示例
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type:application/json
{
"accessToken" : "abcd",
"refreshToken" : "abcd",
"expireIn" : 7200,
"corpId" : "corpxxxx"
}
Enter to Rename, ⇧Enter to Preview
错误码
若调用该接口报错，可根据错误信息在全局错误码文档中查找解决方案。