获取 access_token

该接口用于换取柠檬云 API 的稳定调用凭证。传入商务团队分配的 appId 和 appSecret，成功后返回 JWT 格式的 access_token 及长期 refresh_token；后续所有业务请求均需在 Header 中携带 access token。

注意：access token 最长有效期为 2 小时（7200 秒），refresh token 最长有效期为 30 天。接口应仅在服务端调用，请妥善保存 appSecret、access_token 和 refresh_token，避免在前端、客户端或日志中暴露。

调用模式

普通模式：不传 forceRefresh 或传入 false。当前 access token 剩余有效期大于 5 分钟时，重复调用会返回同一个 access token 及其剩余有效秒数，同时返回当前有效的 refresh token；剩余有效期不大于 5 分钟时，服务会签发新的令牌对。普通模式签发新 access token 后，上一令牌最多仍可使用 5 分钟。

强制刷新模式：传入 forceRefresh: true。服务立即签发新的 access token 和 refresh token，并撤销上一令牌对。该模式同一应用两次调用至少间隔 30 秒，每个自然日最多 20 次，请仅在确有需要时使用。

如何使用

业务请求仅使用 access token，在 HTTP Header 中追加：

Authorization: Bearer <access_token>

当 access token 过期或临近过期时，优先调用 POST /api/v1/open/auth/refresh，使用 refresh token 换取新的令牌对。refresh token 轮换后应立即保存响应中的新 refresh token；刷新失败返回 401 时，客户端应重新登录。

expires_in 和 refresh_expires_in 分别为本次响应中 access token 和 refresh token 的剩余有效时间，单位均为秒。refresh token 为不透明随机凭证，不是 JWT，客户端不得解析其内容。

异常处理

HTTP 状态码	含义
400 Bad Request	请求参数缺失、类型不正确或包含未定义字段
401 Unauthorized	`appId` 或 `appSecret` 无效，或应用已被禁用
429 Too Many Requests	强制刷新过于频繁，或已达到当日强制刷新次数上限

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

返回响应

🟢201

application/json

获取令牌成功

Bodyapplication/json

示例

{
    "code": 0,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expires_in": 7200,
        "refresh_token": "v1.7Jf9...opaque-token...q2K",
        "refresh_expires_in": 2592000
    }
}

🟠400

🟠401

🟠429

🔴500

调用模式#

如何使用#

异常处理#

请求参数

请求示例代码

返回响应

调用模式

如何使用

异常处理