认证鉴权

接口描述

柠檬云使用 JWT Bearer Token 机制保护需要鉴权的业务接口。接入方凭借 appId 与 appSecret 换取访问令牌和刷新令牌，并在业务请求的 Authorization 头中携带访问令牌。

💡

注意：access_token 最长有效期为 2 小时（7200 秒），refresh_token 最长有效期为 30 天。令牌仅应保存在服务端，不要暴露在前端、客户端或日志中。

第一步：获取令牌

使用商务团队分配的 appId 与 appSecret 调用以下接口换取令牌对。

请求地址

POST /api/v1/open/auth/login

Header

Content-Type: application/json

Body 参数

参数名称	参数类型	是否必填	说明
appId	String	是	商务分配的应用 ID
appSecret	String	是	商务分配的应用密钥
forceRefresh	Boolean	否	是否强制签发新令牌对，默认 `false`

示例请求

{
    "appId": "your_app_id",
    "appSecret": "your_app_secret",
    "forceRefresh": false
}

返回值示例

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

返回字段	类型	说明
data.access_token	String	JWT 访问令牌
data.expires_in	Integer	访问令牌剩余有效时间，单位为秒
data.refresh_token	String	不透明刷新令牌，轮换后须保存最新值
data.refresh_expires_in	Integer	刷新令牌剩余有效时间，单位为秒

第二步：在请求中携带令牌

拿到 access_token 后，在需要鉴权的业务请求 Header 中附加：

Authorization: Bearer <access_token>

示例（发票查验）

POST /api/v1/open/invoice-check
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

第三步：刷新令牌

当 access_token 临近过期或已经过期时，使用当前 refresh_token 换取新的令牌对：

POST /api/v1/open/auth/refresh-token
Content-Type: application/json

{
    "refreshToken": "v1.7Jf9...opaque-token...q2K",
    "appId": "your_app_id"
}

刷新成功后，旧 refresh_token 将被轮换。接入方必须立即保存响应中的新 refresh_token；旧令牌仅有约 20 秒的并发宽限期，不能继续作为长期凭证使用。刷新失败并返回 HTTP 401 时，应重新调用获取令牌接口。

常见鉴权异常

HTTP 状态码	含义
401 Unauthorized	令牌无效或已过期，请重新获取
400 Bad Request	请求参数有误，请核实 appId / appSecret
429 Too Many Requests	强制刷新过于频繁，或达到当日强制刷新次数上限

接口描述#

第一步：获取令牌#

第二步：在请求中携带令牌#

第三步：刷新令牌#

常见鉴权异常#

接口描述

第一步：获取令牌

第二步：在请求中携带令牌

第三步：刷新令牌

常见鉴权异常