API 参考

小红书开放平台的所有 HTTP 接口均遵循以下规范：

• Base URL：https://openaccount.xiaohongshu.com（测试环境替换为 https://openaccount.beta.xiaohongshu.com）
• 请求方法：POST（Content-Type: application/json）
• 字符编码：UTF-8
• 时间戳：秒级 Unix 时间戳

接口目录

• 1. 查询授权状态 / 拉起授权页
• 2. 用户授权并获取 code
• 3. 换取 access_token
• 4. 刷新 access_token
• 5. 校验 access_token 有效性
• 6. 获取用户基本信息（min_user_info）
• 7. 用户已授权应用列表
• 8. 用户解除授权
• 9. 创建设备授权（车机 / Web 扫码）
• 10. 轮询设备 Token
• 11. 解除授权（应用服务端主动调用）

统一响应结构

{
  "code": 0,          // 业务错误码，0 表示成功
  "success": true,
  "msg": "成功",
  "data": { ... }     // 业务数据
}

1. 查询授权状态 / 拉起授权页

用户点击「小红书登录」时首先调用此接口，若用户会话有效且已授权过本应用，则直接返回 code；否则返回授权页所需的展示信息。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "authorized": true,           // 是否已授权
    "code": "xhs...",             // authorized=true 时直接返回 code
    "state": "xxx",               // 透传
    "app_name": "你的应用名",
    "app_icon": "https://...",
    "entity": "应用主体",
    "app_type": "移动应用",
    "scopes": [                    // authorized=false 时展示授权页
      {
        "scope": "basic_info",
        "title": "小红书个人资料",
        "sub_title": "用于快速登录，并提供基础的个性化推荐",
        "mandatory": true
      }
    ]
  }
}

2. 用户授权并获取 code

用户在授权页勾选权限并点击「同意授权」后调用，返回授权码 code。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "code": "xhs...",   // 授权码，10 分钟内有效，一次性使用
    "state": "xxx"      // 透传
  }
}

3. 换取 access_token

拿到 code 后换取 access_token 与 refresh_token。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "access_token": "xhs_...",
    "expire_time": 1735660800,         // AT 过期时间（秒级时间戳）
    "refresh_token": "xhs_rt_...",
    "refresh_expire_time": 1751212800, // RT 过期时间（秒级时间戳）
    "open_id": "xxxx",                 // 用户在本应用下的唯一 ID
    "scope": ["basic_info"]            // 用户实际授权的范围
  }
}

4. 刷新 access_token

access_token 过期后使用 refresh_token 换取新的 access_token。 此接口不会延长 refresh_token 的过期时间。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "access_token": "xhs_...",           // 新的 AT
    "expire_time": 1735660800,
    "refresh_token": "xhs_rt_...",       // 新的 RT
    "refresh_expire_time": 1751212800,   // RT 过期时间保持不变
    "open_id": "xxxx",
    "scope": ["basic_info"]
  }
}

5. 校验 access_token 有效性

用于校验 access_token 是否仍然有效，一般在调用业务接口前主动探测。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "access_token": "xhs_...",
    "expire_time": 1735660800,
    "refresh_token": "xhs_rt_...",
    "refresh_expire_time": 1751212800,
    "open_id": "xxxx",
    "scope": ["basic_info"]
  }
}

6. 获取用户基本信息

获取当前授权用户的基本信息。需要在 Header 中携带 access_token。

请求 Header

Authorization: Bearer xhs_...    // access_token

请求参数

无需 body 参数，用户身份从 access_token 中解析。

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "open_id": "xxxx",
    "nickname": "张三",
    "avatar": "https://sns-avatar-qc.xhscdn.com/xxx",
    "gender": 1,        // 0=未知，1=男，2=女
    "region": "上海"
  }
}

7. 用户已授权应用列表

用户在小红书 App「账号与安全 → 已授权的应用」中查看的列表，按授权时间倒序排列。

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "auth_apps": [
      {
        "app_id": "xhs...",
        "app_name": "你的应用",
        "app_icon": "https://...",
        "entity": "应用主体",
        "app_type": "移动应用",
        "auth_time": 1735660800,
        "scopes": [
          { "scope": "basic_info", "title": "...", "sub_title": "..." }
        ]
      }
    ]
  }
}

8. 用户解除授权

用户主动解除对某个应用的授权，解除后该应用持有的 token 立即失效。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功"
}

9. 创建设备授权

Web / 车机扫码授权入口。应用服务端调用此接口获取 device_code 与 user_code， 在浏览器页面或车机屏幕上渲染二维码，用户使用手机小红书 App 扫码授权后， 通过 轮询接口 换取 Token。完整流程见 设备授权文档。

请求参数

响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "device_code": "xhs_dc_7f3a8d1f4b9c4e9f83bd38c8f21d7a72d16f31ab",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://openaccount.xiaohongshu.com/device",
    "verification_uri_complete": "https://openaccount.xiaohongshu.com/device?user_code=WDJB-MJHT",
    "expires_in": 600,
    "interval": 1
  }
}

10. 轮询设备 Token

应用服务端（Web 服务端 / 车企服务端）按 interval 秒的最小间隔轮询此接口。 用户在手机上完成授权后，接口返回 access_token / refresh_token。 轮询规则详见 设备授权文档。

请求参数

等待授权响应示例

37002 与 37009 均为正常轮询中间态，不代表异常。 应用服务端应按 interval 秒继续请求；37009 表示用户已扫码，可将展示二维码的页面（浏览器 / 车机屏幕）切换为「已扫码，请在手机上确认」。

{
  "code": 37002,
  "success": false,
  "msg": "Authorization pending",
  "data": null
}

成功响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "access_token": "xhs_at_xxxxxxxx",
    "expire_time": 1786600000,
    "refresh_token": "xhs_rt_xxxxxxxx",
    "refresh_expire_time": 1802150000,
    "open_id": "5f4cxxxxxxxx",
    "scope": ["basic_info"]
  }
}

完整错误码见 错误码 · 设备授权。

11. 解除授权（应用服务端主动调用）

应用服务端（车企云端 / Web 后端）主动撤销一个 access_token 对应的授权关系。 典型场景：用户在车企 App 内解绑小红书账号、切换账号、注销账号。 成功后，该用户在该应用下持有的 access_token / refresh_token 全部立即失效， 下次业务调用将返回 23001 ACCESS_TOKEN_INVALID。

请求参数

成功响应示例

{
  "code": 0,
  "success": true,
  "msg": "成功",
  "data": {
    "open_id": "5f4cxxxxxxxx",
    "already_revoked": false     // false=本次执行了实际撤销；true=幂等命中（此前已被撤销）
  }
}

幂等语义

• 同一 access_token 重复调用 返回成功，already_revoked=true，不会重复触发 Webhook
• access_token 若已被用户在小红书 App 内解绑，本接口仍返回成功（already_revoked=true），便于接入方对齐状态
• access_token 从未存在 / 已过期 / 应用不匹配 → 返回 37010 / 37011，请停止重试

常见错误码

常见问题

• 调用接口报错？先查 错误码表
• Token 频繁失效？检查 refresh_token 是否已过期（180 天）
• PKCE 校验失败？确认 code_challenge 与 code_verifier 的 SHA256 关系