设备授权（Device Authorization Grant）

最后更新：2026-08-19 · 阅读约 10 分钟

Web 应用与车机应用统一采用的授权模式，完整遵循 RFC 8628 标准。应用服务端调用接口获取二维码后，在 Web 页面或车机屏幕上展示，用户使用手机小红书 App 扫码并在手机上完成授权，应用服务端通过轮询取得 Access Token。

✓

为什么 Web 与车机共用这套流程

Web 与车机都不适合让用户在当前设备上直接登录： Web 端要求用户输入账号密码风险高，车机端更是输入不便。设备授权模式把用户授权动作整体转移到用户手机，当前设备（浏览器 / 车机）只负责展示二维码并轮询结果，既提升安全性又统一体验，因此在管理中心共用同一套申请入口。

适用场景

Web 应用：网页在浏览器中展示二维码，用户手机扫码授权，服务端轮询获得 Token；适用于 Web 端免密登录、后端服务应用授权等场景。
车机应用：车载中控在车机屏幕上展示二维码，用户手机扫码授权，车企服务端轮询获得 Token；适用于车机无浏览器 / 输入不便的场景。

RFC 8628 协议本身也适用于智能电视、命令行工具、IoT 等无键盘设备，如有其他形态接入需求可联系我们评估。

核心概念

概念	说明
`device_code`	高熵设备凭证，应用服务端使用它轮询 Token，禁止下发到浏览器、车机屏幕或前端页面
`user_code`	用户核对短码，格式 `XXXX-XXXX`，向用户展示时称为「验证码」
`verification_uri`	基础授权地址，需用户手动输入 user_code
`verification_uri_complete`	已携带 user_code 的完整授权地址，Web 页面 / 车机屏幕只应用它渲染二维码
`expires_in`	device_code 与 user_code 的整体有效期（秒），默认 10 分钟
`interval`	轮询最小间隔（秒），默认 5 秒

⚠

术语约定

API 侧统一使用 device_code / user_code 精确术语；面向终端用户展示时（手机小红书授权页、Web 页面、车机屏幕），统一称为「验证码」，避免用户困惑。

授权时序图

  Web / 车机端      应用服务端         小红书授权中心      用户手机 App
   │                    │                    │                    │
(1)│───── 请求二维码 ───>│                    │                    │
   │                    │                    │                    │
   │                (2) │─ POST /device/code >│                    │
   │                    │<── device_code /────│                    │
   │                    │    user_code /      │                    │
   │                    │    verification_uri │                    │
   │                    │                    │                    │
(3)│<── 二维码 & 短码 ───│                    │                    │
   │                    │                    │                    │
   │  (4) 用户使用手机扫码 verification_uri_complete                  │
   │                    │                    │                    │
   │                    │                    │<── 打开授权 H5 ─────│
   │                    │                    │─── 拉起 App 授权 ──>│
   │                    │                    │<── 用户同意授权 ────│
   │                    │                    │                    │
   │                (5) │─ POST /device/token│                    │
   │                    │  (轮询，每 interval 秒)                    │
   │                    │<── 37002 / 37009 ──│  (授权未完成)        │
   │                    │                    │                    │
   │                    │─ POST /device/token│                    │
   │                    │<── access_token ───│  (授权完成)          │
   │                    │    refresh_token   │                    │
   │                    │    open_id / scope │                    │
(6)│<── 授权成功 ────────│                    │                    │

💡

Web 与车机共用同一套接入方案

Web 应用与车机应用接入路径完全一致： app_secret 由后端持有、服务端调用创建设备授权接口、前端页面 / 车机屏幕渲染二维码、用户手机扫码授权、服务端轮询获得 Token。 Token 生命周期（access 2h / refresh 180d）也完全一致。二者唯一的差异只在二维码展示的载体：Web 应用在浏览器页面展示、车机应用在车机屏幕展示。因此在管理中心共用同一套申请入口。

接入指引（应用服务端视角）

Step 1：创建设备授权

用户在 Web 页面点击「扫码登录」或在车机上发起授权时，应用服务端调用创建设备授权接口获取 device_code、user_code、verification_uri_complete。

安全要求

app_secret 与 device_code 只能保存在应用服务端，禁止下发到浏览器、车机屏幕、WebView 或任何前端。二维码中禁止包含 device_code，仅使用 verification_uri_complete 渲染。

Step 2：前端展示二维码 + 用户扫码

Web 页面 / 车机屏幕使用 verification_uri_complete 渲染二维码
二维码旁同时展示 user_code（标注为「验证码」），供用户与手机页面核对
用户使用小红书 App 扫码，打开手机上的授权 H5
H5 展示应用信息、权限范围、验证码，与前端页面上的验证码保持一致
用户在小红书 App 内完成授权（勾选权限 → 同意）

Step 3：轮询获取 Token

应用服务端调用轮询设备 Token 接口，按接口返回的 interval 秒间隔轮询：

收到 37002 DEVICE_AUTHORIZATION_PENDING 或 37009 DEVICE_AUTHORIZATION_SCANNED：保持当前间隔继续轮询。
37009 表示用户已扫码但尚未确认，设备端可将界面切换为「已扫码，请在手机上确认」，提升用户体验
收到 37003 DEVICE_SLOW_DOWN：将轮询间隔增加 5 秒后继续
收到 Token（code=0）：立即停止轮询，妥善保存 access_token / refresh_token
收到终态错误（37001 过期 / 37004 已用 / 31002 用户拒绝等）：立即停止轮询，展示相应文案
device_code 过期后，需重新调用创建接口获取新的二维码

Access Token 生命周期

拿到 access_token / refresh_token 后，与其他授权模式完全一致： access_token 有效期 2 小时，refresh_token 有效期 180 天。详见 OAuth 2.0 授权流程的「Token 生命周期」章节。

与授权码模式对比

维度	授权码模式（Authorization Code）	设备授权模式（Device Grant）
用户授权入口	SDK 拉起手机小红书 App	用户扫二维码
凭证类型	authorization `code`	`device_code` + `user_code`
换取方式	SDK 回调返回 code，App 内完成 token 交换	服务端轮询获取 token
redirect_uri	SDK 内建，无需开发者配置	不涉及
典型场景	移动 App（iOS / Android）	Web 应用扫码登录、车机扫码授权

安全要求

app_secret、device_code、access_token、refresh_token 只能保存在应用服务端，禁止下发到浏览器、WebView 或车机屏幕
Token 必须加密落库，禁止写入日志
二维码禁止包含 device_code，只能使用 verification_uri_complete
前端页面 / 车机屏幕需在二维码旁显示 user_code（标注为「验证码」），便于用户核对
应用服务端与小红书之间的请求必须使用 HTTPS
授权成功、用户拒绝、device_code 过期或收到 37004 DEVICE_CODE_USED 后，禁止继续复用该 device_code

常见错误码

设备授权流程涉及的错误码集中在 37000 - 37009 段，完整列表见错误码 · 设备授权。

下一步

查看创建设备授权接口与轮询设备 Token 接口
查看 37xxx 错误码处理异常场景
查看授权范围（Scope）选择合适的权限