Auth(自带登录)

独立部署(形态 B)时,用户没有 cloudreve 登录态,cr4sync 提供自有登录端点,代理 cloudreve 鉴权。

server 不存储密码/token/会话:登录只是转发到 cloudreve,TokenSet 返回给前端,前端写入 localStorage。所有 /api/v4/cr4sync/auth/* 不加鉴权中间件(用户还没 token)。

`POST /api/v4/cr4sync/auth/login`

账密登录。code=0 返回 token;code=203 需要 2FA。

请求 body

{
  "email": "you@example.com",
  "password": "your-password",
  "captcha": "1234",
  "ticket": "captcha-ticket"
}

字段	类型	必填	说明
`email`	string	✓	Cloudreve 账号邮箱
`password`	string	✓	密码
`captcha`	string?	✗	验证码:图形验证码填用户输入;Turnstile/reCAPTCHA 填 widget 返回的 token
`ticket`	string?	✗	图形验证码的 ticket(从 `/auth/captcha` 响应取);Turnstile/reCAPTCHA 时与 `captcha` 同值

响应 200

直接成功:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "token": {
      "access_token": "...",
      "refresh_token": "...",
      "access_expires": "2026-07-03T...",
      "refresh_expires": "2026-08-..."
    }
  },
  "request_id": "-"
}

需要 2FA:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "session_id": "2fa-session-id"
  },
  "request_id": "-"
}

`POST /api/v4/cr4sync/auth/login/2fa`

提交 OTP 验证码完成登录。

请求 body

{
  "otp": "123456",
  "session_id": "从上一步获取"
}

响应 200

与 /auth/login 成功响应相同结构,data.token 已填充。

`GET /api/v4/cr4sync/auth/captcha/status`

查询 cloudreve 验证码类型与配置。是否开启验证码由 cloudreve GET /site/config/login 的 login_captcha 字段决定 (true=开启); 验证码类型与 site keys 从 GET /site/config/basic 拿。login_captcha=false 时 enabled=false,前端不加载验证码 widget。

响应 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "enabled": true,
    "captcha_type": "normal|turnstile|recaptcha|cap|null",
    "captcha_ReCaptchaKey": "site-key-or-null",
    "turnstile_site_id": "site-id-or-null",
    "captcha_cap_instance_url": null,
    "captcha_cap_site_key": null
  },
  "request_id": "-"
}

字段	说明
`enabled`	是否启用了登录验证码
`captcha_type`	验证码类型:`normal`(图形)/`turnstile`/`recaptcha`/`cap`/`null`
`captcha_ReCaptchaKey`	reCAPTCHA site key(仅 `recaptcha` 类型有值)
`turnstile_site_id`	Turnstile site key(仅 `turnstile` 类型有值)
`captcha_cap_*`	Cap 验证码配置(仅 `cap` 类型,当前前端未支持)

`GET /api/v4/cr4sync/auth/captcha`

图形验证码(captcha_type=normal 时用)。返回 JSON,前端拿 image 渲染图片、ticket 在登录时提交。

响应 200

{
  "code": 0,
  "msg": "ok",
  "data": {
    "image": "data:image/png;base64,iVBOR...",
    "ticket": "captcha-ticket-string"
  },
  "request_id": "-"
}

未启用图形验证码时返回 404。

`POST /api/v4/cr4sync/auth/token/refresh`

用 refresh_token 换新 token 对(长任务 token 续期)。

请求 body

{
  "refresh_token": "..."
}

响应 200

与 /auth/login 成功响应相同结构。

扫码登录 (QR)

依赖 cloudreve 安装了 qr-login-relay 插件, 插件来自 @fsjdb342 三步式:

POST /api/v4/cr4sync/auth/qr/create — 创建扫码会话,返回二维码载荷
GET /api/v4/cr4sync/auth/qr/status/:id — 1500ms 轮询状态
GET /api/v4/cr4sync/auth/qr/result/:id — 取解密结果,返回 token

`POST /auth/qr/create`

响应:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "session_id": "relay-xxx",
    "qr_payload": "{...}",
    "cr4_session_id": "01J5...",
    "expires_at": 1717000600
  },
  "request_id": "-"
}

session_id:relay 内部 ID
qr_payload:前端用它渲染二维码
cr4_session_id:前端用它查 /auth/qr/status/{id} 和 /auth/qr/result/{id}
若 relay 未部署(不健康),返回 500

`GET /auth/qr/status/:id`

{
  "code": 0,
  "msg": "ok",
  "data": {
    "status": "pending|scanned|authorized|expired"
  },
  "request_id": "..."
}

`GET /auth/qr/result/:id`

{
  "code": 0,
  "msg": "ok",
  "data": {
    "token": {
      "access_token": "...",
      "refresh_token": "...",
      "access_expires": "...",
      "refresh_expires": "..."
    }
  },
  "request_id": "..."
}

一次扫码会话 TTL 120s,过期需重新 POST /auth/qr/create。

Keyboard shortcuts

cr4sync 使用文档