账号与认证

POST /cm/auth/2fa/disable

{password, code}：当前密码 + 验证器验证码或恢复码关闭两步验证，下线其他设备

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`code`	''（空值时回退）
JSON body	`password`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
404	'接口不存在'

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/2fa/disable' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "code": "`"}'
ˋˋˋ

### 返回类型

此分支使用专用处理器、文件或事件流响应，或在共享分支中组装 JSON。具体结构见对应专题；文件流不能按 JSON 解析。

实现定位：ˋbackend/cm_server.py:1990ˋ。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/2fa/enable

校验 {code} 后开启 TOTP；返回仅显示一次的 10 枚 recoveryCodes，下线其他设备

**权限**：Bearer。

### 请求参数

\| 位置 \| 字段 \| 默认/读取方式 \|
\| --- \| --- \| --- \|
\| JSON body \| ˋcodeˋ \| ''（空值时回退） \|
\| JSON body \| ˋpasswordˋ \| ''（空值时回退） \|

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 参数校验与业务错误

\| HTTP \| 服务端校验说明 \|
\| --- \| --- \|
\| 404 \| '接口不存在' \|

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

### 请求模板

将 ˋ{id}ˋ 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

ˋˋˋbash
curl --request POST 'https://music.20110208.xyz/cm/auth/2fa/enable' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "code": "<code>"}'
ˋˋˋ

### 返回类型

此分支使用专用处理器、文件或事件流响应，或在共享分支中组装 JSON。具体结构见对应专题；文件流不能按 JSON 解析。

实现定位：ˋbackend/cm_server.py:1988ˋ。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/2fa/login

{challengeToken, code}：完成第二步登录，返回 {token, user}；5 分钟有效，失败每账号 5 次/5 分钟

**权限**：公开。

### 请求参数

\| 位置 \| 字段 \| 默认/读取方式 \|
\| --- \| --- \| --- \|
\| JSON body \| ˋchallengeTokenˋ \| ''（空值时回退） \|
\| JSON body \| ˋcodeˋ \| ''（空值时回退） \|

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 请求模板

将 ˋ{id}ˋ 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

ˋˋˋbash
curl --request POST 'https://music.20110208.xyz/cm/auth/2fa/login' \
  --header 'Content-Type: application/json' \
  --data '{"challengeToken": "<challengeToken>", "code": "<code>"}'
ˋˋˋ

### 返回结构

以下是实现中直接返回的字段与取值表达式，**不是一次真实请求的响应示例**。条件分支可能返回不同结构。

HTTP 200

\| 字段 \| 取值/生成逻辑 \|
\| --- \| --- \|
\| ˋtokenˋ \| <code>token` |
| `user` | `public_user(u)` |

实现定位：`backend/cm_server.py:1976`。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/2fa/setup

校验当前密码 {password}，返回待绑定密钥 secret 和 otpauth uri（10 分钟，会话绑定）

**权限**：Bearer。

### 请求参数

| 位置 | 字段 | 默认/读取方式 |
| --- | --- | --- |
| JSON body | `code` | &#x27;&#x27;（空值时回退） |
| JSON body | `password` | &#x27;&#x27;（空值时回退） |

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 参数校验与业务错误

| HTTP | 服务端校验说明 |
| --- | --- |
| 404 | &#x27;接口不存在&#x27; |

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

### 请求模板

将 `{id}` 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

```bash
curl --request POST 'https://music.20110208.xyz/cm/auth/2fa/setup' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "code": "`"}'
ˋˋˋ

### 返回类型

此分支使用专用处理器、文件或事件流响应，或在共享分支中组装 JSON。具体结构见对应专题；文件流不能按 JSON 解析。

实现定位：ˋbackend/cm_server.py:1986ˋ。接口参数和返回条件均来自该路由分支。


## GET /cm/auth/2fa/status

两步验证状态及剩余恢复码数量

**权限**：Bearer。

### 请求模板

将 ˋ{id}ˋ 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

ˋˋˋbash
curl --request GET 'https://music.20110208.xyz/cm/auth/2fa/status' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'
ˋˋˋ

### 返回结构

以下是实现中直接返回的字段与取值表达式，**不是一次真实请求的响应示例**。条件分支可能返回不同结构。

HTTP 200

\| 字段 \| 取值/生成逻辑 \|
\| --- \| --- \|
\| ˋ响应体ˋ \| <code>cm_2fa.status(u['id'])` |

实现定位：`backend/cm_server.py:1983`。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/email/code

账号与认证 · /auth/email/code

**权限**：路由未直接调用登录检查；委托处理器可能另行校验，见说明。

### 请求参数

| 位置 | 字段 | 默认/读取方式 |
| --- | --- | --- |
| JSON body | `email` | &#x27;&#x27;（空值时回退） |

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 参数校验与业务错误

| HTTP | 服务端校验说明 |
| --- | --- |
| 400 | &#x27;邮箱格式不正确&#x27; |
| 409 | &#x27;该邮箱已注册，请直接登录或换用其他邮箱&#x27; |
| 429 | f&quot;发送太频繁，请 {60 - (now - row[&#x27;sent_at&#x27;])} 秒后再试&quot; |
| 500 | &#x27;邮件服务未配置，请联系管理员&#x27; |
| 502 | &#x27;邮件发送失败，请稍后重试或检查邮箱地址&#x27; |

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

### 请求模板

将 `{id}` 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

```bash
curl --request POST 'https://music.20110208.xyz/cm/auth/email/code' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"email": "<email>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`
`ttl`	`300`

实现定位：backend/cm_server.py:1835。接口参数和返回条件均来自该路由分支。

POST /cm/auth/internal

账号与认证 · /auth/internal

权限：路由未直接调用登录检查；委托处理器可能另行校验，见说明。

请求参数

位置	字段	默认/读取方式
JSON body	`password`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
401	'内部密码错误'
503	'内部登录未启用'
e.status	str(e)

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/internal' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`token`	`token`
`user`	`public_user(u)`

HTTP 200

字段	取值/生成逻辑
`响应体`	`pending`

实现定位：backend/cm_server.py:1998。接口参数和返回条件均来自该路由分支。

POST /cm/auth/login

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`password`	''（空值时回退）
JSON body	`username`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
401	'用户名或密码错误'
403	str(e)
e.status	str(e)

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/login' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "username": "<username>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`token`	`token`
`user`	`public_user(u)`

HTTP 200

字段	取值/生成逻辑
`响应体`	`pending`

实现定位：backend/cm_server.py:2021。接口参数和返回条件均来自该路由分支。

POST /cm/auth/login/email

邮箱验证码登录 {email, code}，开启 2FA 时返回验证挑战，否则返回 {token, user}（验证码与注册码命名空间隔离）

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`code`	''（空值时回退）
JSON body	`email`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
400	'请填写邮箱与验证码'
403	'账号已被禁用，请联系管理员'
404	'该邮箱未注册'
e.status	str(e)

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/login/email' \
  --header 'Content-Type: application/json' \
  --data '{"code": "`", "email": "<email>"}'
ˋˋˋ

### 返回结构

以下是实现中直接返回的字段与取值表达式，**不是一次真实请求的响应示例**。条件分支可能返回不同结构。

HTTP 200

\| 字段 \| 取值/生成逻辑 \|
\| --- \| --- \|
\| ˋtokenˋ \| <code>token` |
| `user` | `public_user(u)` |

HTTP 200

| 字段 | 取值/生成逻辑 |
| --- | --- |
| `响应体` | `pending` |

实现定位：`backend/cm_server.py:2072`。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/login/email/code

发送**登录**邮箱验证码（要求邮箱已注册；60s 冷却 + 每 IP 每小时 10 条）

**权限**：公开。

### 请求参数

| 位置 | 字段 | 默认/读取方式 |
| --- | --- | --- |
| JSON body | `email` | &#x27;&#x27;（空值时回退） |

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 参数校验与业务错误

| HTTP | 服务端校验说明 |
| --- | --- |
| 400 | &#x27;邮箱格式不正确&#x27; |
| 404 | &#x27;该邮箱未注册，请先注册或在设置中绑定邮箱&#x27; |
| 429 | &#x27;当前网络请求验证码过于频繁，请稍后再试&#x27; |
| 429 | f&quot;发送太频繁，请 {60 - (now - row[&#x27;sent_at&#x27;])} 秒后再试&quot; |
| 500 | &#x27;邮件服务未配置，请联系管理员&#x27; |
| 502 | &#x27;邮件发送失败，请稍后重试&#x27; |

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

### 请求模板

将 `{id}` 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

```bash
curl --request POST 'https://music.20110208.xyz/cm/auth/login/email/code' \
  --header 'Content-Type: application/json' \
  --data '{"email": "<email>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`
`ttl`	`300`

实现定位：backend/cm_server.py:2044。接口参数和返回条件均来自该路由分支。

POST /cm/auth/logout

退出当前设备并撤销会话

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/logout' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`

实现定位：backend/cm_server.py:2153。接口参数和返回条件均来自该路由分支。

GET /cm/auth/me

当前账户资料与统计

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request GET 'https://music.20110208.xyz/cm/auth/me' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`_payload_me(require_user(handler))`

实现定位：backend/cm_server.py:2181。接口参数和返回条件均来自该路由分支。

GET /cm/auth/passkeys

列出本账号通行密钥（不返回公钥）；各 HTTPS 域名独立绑定

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request GET 'https://music.20110208.xyz/cm/auth/passkeys' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`cm_passkeys.listing(u['id'])`

实现定位：backend/cm_server.py:1941。接口参数和返回条件均来自该路由分支。

POST /cm/auth/passkeys/delete

撤销 {id,password,factor}；须密码及已启用的二次验证

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`factor`	''（空值时回退）
JSON body	`id`	''（空值时回退）
JSON body	`password`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/passkeys/delete' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"id": "<id>", "password": "<password>", "factor": "<factor>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`cm_passkeys.remove(u['id'], str(body.get('id') or ''), str(body.get('password') or ''), str(body.get('factor') or '`

实现定位：backend/cm_server.py:1947。接口参数和返回条件均来自该路由分支。

POST /cm/auth/passkeys/login/options

通行密钥登录选项；强制用户验证

权限：公开。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/passkeys/login/options'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`cm_passkeys.begin(origin)`

实现定位：backend/cm_server.py:1933。接口参数和返回条件均来自该路由分支。

POST /cm/auth/passkeys/login/verify

{challengeToken,credential,device,platform}；验签成功直接返回 {token,user}，无需额外 2FA 或密保

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`challengeToken`	''（空值时回退）
JSON body	`credential`	{}（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/passkeys/login/verify' \
  --header 'Content-Type: application/json' \
  --data '{"credential": "<credential>", "challengeToken": "<challengeToken>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`token`	`r['token']`
`user`	`public_user(cm_db.get_user(r['uid']))`

实现定位：backend/cm_server.py:1935。接口参数和返回条件均来自该路由分支。

POST /cm/auth/passkeys/register/options

绑定选项 {password,factor}；开启 2FA/密保须验证当前因素；挑战绑定会话和 Origin，5 分钟单次有效

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`factor`	''（空值时回退）
JSON body	`password`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/passkeys/register/options' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "factor": "<factor>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`cm_passkeys.begin(origin, u['id'], u['_token'], str(body.get('password') or ''), str(body.get('factor') or ''))`

实现定位：backend/cm_server.py:1943。接口参数和返回条件均来自该路由分支。

POST /cm/auth/passkeys/register/verify

完成绑定 {challengeToken,credential,name}；强制用户验证和可发现凭据

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`challengeToken`	''（空值时回退）
JSON body	`credential`	{}（空值时回退）
JSON body	`name`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/passkeys/register/verify' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"credential": "<credential>", "challengeToken": "<challengeToken>", "name": "<name>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`cm_passkeys.finish(origin, str(body.get('challengeToken') or ''), body.get('credential') or {}, u['id'], u['_token'], str(body.get`

实现定位：backend/cm_server.py:1945。接口参数和返回条件均来自该路由分支。

POST /cm/auth/password/code

发送找回密码邮箱验证码（要求邮箱已注册；reset: 命名空间；60s 冷却 + 每 IP 每小时 10 条）

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`email`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
400	'邮箱格式不正确'
403	'系统账号不支持找回密码'
403	'账号已被禁用，请联系管理员'
404	'该邮箱未注册，请先注册或在设置中绑定邮箱'
429	f"发送太频繁，请 {60 - (now - row['sent_at'])} 秒后再试"
500	'邮件服务未配置，请联系管理员'
502	'邮件发送失败，请稍后重试'

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/password/code' \
  --header 'Content-Type: application/json' \
  --data '{"email": "<email>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`
`ttl`	`300`

实现定位：backend/cm_server.py:2099。接口参数和返回条件均来自该路由分支。

POST /cm/auth/password/reset

邮箱验证码重置密码 {email, code, newPassword}；成功后吊销该账号全部会话与通行证授权

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`code`	''（空值时回退）
JSON body	`email`	''（空值时回退）
JSON body	`newPassword`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
400	'新密码长度需 6~64 位'
400	'请填写邮箱与验证码'
400	'邮箱格式不正确'
403	'系统账号不支持找回密码'
403	'账号已被禁用，请联系管理员'
404	'该邮箱未注册'

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/password/reset' \
  --header 'Content-Type: application/json' \
  --data '{"newPassword": "<newPassword>", "code": "`", "email": "<email>"}'
ˋˋˋ

### 返回结构

以下是实现中直接返回的字段与取值表达式，**不是一次真实请求的响应示例**。条件分支可能返回不同结构。

HTTP 200

\| 字段 \| 取值/生成逻辑 \|
\| --- \| --- \|
\| ˋokˋ \| <code>True` |
| `username` | `u['username']` |
| `nickname` | `u['nickname']` |

实现定位：`backend/cm_server.py:2129`。接口参数和返回条件均来自该路由分支。


## POST /cm/auth/phone/code

账号与认证 · /auth/phone/code

**权限**：路由未直接调用登录检查；委托处理器可能另行校验，见说明。

### 请求参数

| 位置 | 字段 | 默认/读取方式 |
| --- | --- | --- |
| JSON body | `ctcode` | &#x27;86&#x27;（空值时回退） |
| JSON body | `phone` | 未在 get 中指定 |

> 表格列出实际代码读取的字段；get 的默认值不等于业务可省略。必填、长度和取值约束见下方校验及关联专题。

### 参数校验与业务错误

| HTTP | 服务端校验说明 |
| --- | --- |
| 400 | &#x27;手机号格式不正确&#x27; |
| 409 | &#x27;该手机号已注册，请直接登录或换用其他号码&#x27; |
| 429 | &#x27;当前网络请求验证码过于频繁，请稍后再试&#x27; |
| 429 | &#x27;该号码今日验证码次数已达上限，请明天再试&#x27; |
| 429 | f&#x27;发送太频繁，请 {SMS_COOLDOWN - (now - last)} 秒后再试&#x27; |
| 502 | _friendly_sms_error(e) |

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

### 请求模板

将 `{id}` 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

```bash
curl --request POST 'https://music.20110208.xyz/cm/auth/phone/code' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"phone": "<phone>", "ctcode": "<ctcode>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`
`ttl`	`300`
`mode`	`mode`
`hint`	`cm_sms.describe()`

实现定位：backend/cm_server.py:1861。接口参数和返回条件均来自该路由分支。

POST /cm/auth/register

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`email`	''（空值时回退）
JSON body	`emailCode`	''（空值时回退）
JSON body	`nickname`	''（空值时回退）
JSON body	`password`	''（空值时回退）
JSON body	`phone`	未在 get 中指定
JSON body	`phoneCode`	''（空值时回退）
JSON body	`username`	''（空值时回退）

参数校验与业务错误

HTTP	服务端校验说明
400	'密码长度需 6~64 位'
400	'手机号与验证码需同时填写'
400	'注册需完成手机或邮箱验证'
400	'用户名需 2~24 位字母/数字/下划线/中文'
400	'邮箱格式不正确'
409	'用户名已被占用'
409	'该手机号已注册，请直接登录'
409	'该邮箱已注册，请直接登录'

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/register' \
  --header 'Content-Type: application/json' \
  --data '{"phone": "<phone>", "password": "<password>", "username": "<username>", "emailCode": "<emailCode>", "phoneCode": "<phoneCode>", "nickname": "<nickname>", "email": "<email>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`token`	`token`
`user`	`public_user(cm_db.get_user(uid))`

实现定位：backend/cm_server.py:1890。接口参数和返回条件均来自该路由分支。

DELETE /cm/auth/security-question

关闭密保 {password,answer}；需当前密码和原答案，下线其他设备

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`answer`	''（空值时回退）
JSON body	`password`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request DELETE 'https://music.20110208.xyz/cm/auth/security-question' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "answer": "<answer>"}'

返回类型

此分支使用专用处理器、文件或事件流响应，或在共享分支中组装 JSON。具体结构见对应专题；文件流不能按 JSON 解析。

实现定位：backend/cm_server.py:1966。接口参数和返回条件均来自该路由分支。

GET /cm/auth/security-question

登录密保状态：{enabled, question, twoFactorEnabled}；不返回答案或哈希

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request GET 'https://music.20110208.xyz/cm/auth/security-question' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`enabled`	`state['securityQuestionEnabled']`
`question`	`state['securityQuestion']`
`twoFactorEnabled`	`state['enabled']`

实现定位：backend/cm_server.py:1961。接口参数和返回条件均来自该路由分支。

POST /cm/auth/security-question

开启密保 {password,question,answer}；与验证器 2FA 互斥；验证当前密码并下线其他设备

权限：Bearer。

请求参数

位置	字段	默认/读取方式
JSON body	`answer`	''（空值时回退）
JSON body	`password`	''（空值时回退）
JSON body	`question`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/security-question' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"password": "<password>", "question": "<question>", "answer": "<answer>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`响应体`	`result`

实现定位：backend/cm_server.py:1964。接口参数和返回条件均来自该路由分支。

POST /cm/auth/security-question/login

完成密保登录 {challengeToken,answer}；返回 {token,user}，5 分钟有效且单次消费

权限：公开。

请求参数

位置	字段	默认/读取方式
JSON body	`answer`	''（空值时回退）
JSON body	`challengeToken`	''（空值时回退）

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request POST 'https://music.20110208.xyz/cm/auth/security-question/login' \
  --header 'Content-Type: application/json' \
  --data '{"challengeToken": "<challengeToken>", "answer": "<answer>"}'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`token`	`c['token']`
`user`	`public_user(u)`

实现定位：backend/cm_server.py:1955。接口参数和返回条件均来自该路由分支。

GET /cm/auth/sessions

在线设备列表 {max:null,sessions}；数量不限，超过 5 台时客户端提示风险

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request GET 'https://music.20110208.xyz/cm/auth/sessions' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`max`	`None`
`sessions`	`cm_db.list_sessions(u['id'], u.get('_token'))`

实现定位：backend/cm_server.py:2158。接口参数和返回条件均来自该路由分支。

DELETE /cm/auth/sessions/others

下线其他设备

权限：Bearer。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request DELETE 'https://music.20110208.xyz/cm/auth/sessions/others' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`
`removed`	`removed`

实现定位：backend/cm_server.py:2171。接口参数和返回条件均来自该路由分支。

DELETE /cm/auth/sessions/{id}

下线指定设备

权限：Bearer。

请求参数

位置	字段	默认/读取方式
path	`id`	路径占位符；按业务替换

参数校验与业务错误

HTTP	服务端校验说明
404	'设备不存在或已下线'

说明中的变量表达式表示运行时值；另有统一的认证、频控和上游错误。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request DELETE 'https://music.20110208.xyz/cm/auth/sessions/{id}' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`ok`	`True`

实现定位：backend/cm_server.py:2165。接口参数和返回条件均来自该路由分支。

GET /cm/auth/sms

账号与认证 · /auth/sms

权限：路由未直接调用登录检查；委托处理器可能另行校验，见说明。

请求模板

将 {id} 等占位符和字段值替换为实际数据，令牌只使用你自己的 CurrentMusic 会话。

curl --request GET 'https://music.20110208.xyz/cm/auth/sms' \
  --header 'Authorization: Bearer YOUR_CURRENTMUSIC_TOKEN'

返回结构

以下是实现中直接返回的字段与取值表达式，不是一次真实请求的响应示例。条件分支可能返回不同结构。

HTTP 200

字段	取值/生成逻辑
`mode`	`cm_sms.mode()`
`hint`	`cm_sms.describe()`

实现定位：backend/cm_server.py:1857。接口参数和返回条件均来自该路由分支。

POST /cm/auth/2fa/disable​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/internal​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/login​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/login/email​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/logout​

请求模板​

返回结构​

GET /cm/auth/me​

请求模板​

返回结构​

GET /cm/auth/passkeys​

请求模板​

返回结构​

POST /cm/auth/passkeys/delete​

请求参数​

请求模板​

返回结构​

POST /cm/auth/passkeys/login/options​

请求模板​

返回结构​

POST /cm/auth/passkeys/login/verify​

请求参数​

请求模板​

返回结构​

POST /cm/auth/passkeys/register/options​

请求参数​

请求模板​

返回结构​

POST /cm/auth/passkeys/register/verify​

请求参数​

请求模板​

返回结构​

POST /cm/auth/password/code​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/password/reset​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

POST /cm/auth/register​

请求参数​

参数校验与业务错误​

请求模板​

返回结构​

DELETE /cm/auth/security-question​

请求参数​

请求模板​

返回类型​

GET /cm/auth/security-question​

请求模板​

返回结构​

POST /cm/auth/security-question​

请求参数​

请求模板​

返回结构​

POST /cm/auth/security-question/login​

请求参数​

请求模板​

返回结构​

GET /cm/auth/sessions​

请求模板​

POST /cm/auth/2fa/disable

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/internal

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/login

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/login/email

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/logout

请求模板

返回结构

GET /cm/auth/me

请求模板

返回结构

GET /cm/auth/passkeys

请求模板

返回结构

POST /cm/auth/passkeys/delete

请求参数

请求模板

返回结构

POST /cm/auth/passkeys/login/options

请求模板

返回结构

POST /cm/auth/passkeys/login/verify

请求参数

请求模板

返回结构

POST /cm/auth/passkeys/register/options

请求参数

请求模板

返回结构

POST /cm/auth/passkeys/register/verify

请求参数

请求模板

返回结构

POST /cm/auth/password/code

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/password/reset

请求参数

参数校验与业务错误

请求模板

返回结构

POST /cm/auth/register

请求参数

参数校验与业务错误

请求模板

返回结构

DELETE /cm/auth/security-question

请求参数

请求模板

返回类型

GET /cm/auth/security-question

请求模板

返回结构

POST /cm/auth/security-question

请求参数

请求模板

返回结构

POST /cm/auth/security-question/login

请求参数

请求模板

返回结构

GET /cm/auth/sessions

请求模板