登录认证
登录、刷新令牌、退出、改口令、动态口令(TOTP)、找回密码、图形验证码与超管代登录。登录接口无需认证。
auth登录认证鉴权: 无需鉴权13 个接口获取图形验证码
GET
/api/v2/auth/captcha鉴权: 无需鉴权
登录
POST
/api/v2/auth/login鉴权: 无需鉴权
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| captcha_code | string | — | 图形验证码上显示的字符。 |
| captcha_id | string | — | 图形验证码 id,来自 GET /auth/captcha;连续登录失败后必填。 |
| password | string | 必填 | 登录口令。 |
| totp_code | string | — | 动态口令(TOTP)的 6 位当前码,或一个未用过的恢复码(XXXXX-XXXXX,用后作废);账号启用动态口令时必填。 |
| username | string | 必填 | 用户名 |
| verify_code | string | — | 登录二次验证码。账号开了邮件/短信验证码登录(login_verify)时必填,先经 POST /verify-codes(purpose=login)获取。 |
退出登录
POST
/api/v2/auth/logout鉴权: 用户
修改口令
PUT
/api/v2/auth/password鉴权: 用户
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| new_password | string | 必填 | 新口令,8 到 128 个字符。 |
| old_password | string | 必填 | 原口令。 |
找回密码
POST
/api/v2/auth/password-reset鉴权: 无需鉴权
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| channel | string | 必填 | 按邮箱还是手机号找回。 |
| code | string | 必填 | 发到 target 的验证码(POST /verify-codes,purpose=reset_password)。 |
| new_password | string | 必填 | 新口令,8 到 128 个字符。 |
| target | string | 必填 | 账号绑定的邮箱或手机号。 |
刷新令牌
POST
/api/v2/auth/refresh鉴权: 无需鉴权
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| refresh_token | string | 必填 | 刷新令牌,用来换新的一对令牌。 |
超管代登录
POST
/api/v2/auth/sso鉴权: 无需鉴权
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sso_ticket | string | 必填 | 超管签发的登录票:licwire 信封(kind sso_ticket)字节的 base64url(无填充)。 |
管理员切换到用户
POST
/api/v2/auth/switch鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_id | integer | 必填 | 用户 ID |
凭切换票登录
POST
/api/v2/auth/switch-login鉴权: 无需鉴权
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| switch_ticket | string | 必填 | 管理员换到的一次性切换票。 |
管理员换一张切换到用户的一次性票
POST
/api/v2/auth/switch-ticket鉴权: 仅管理员
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_id | integer | 必填 | 用户 ID |
生成动态口令密钥
POST
/api/v2/auth/totp鉴权: 用户
启用动态口令
PUT
/api/v2/auth/totp鉴权: 用户
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 必填 | 发到 target 的验证码(POST /verify-codes,purpose=reset_password)。 |
关闭动态口令
DELETE
/api/v2/auth/totp鉴权: 用户
请求体 application/json
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| code | string | 必填 | 发到 target 的验证码(POST /verify-codes,purpose=reset_password)。 |
登录认证对象
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| access_token | string | — | 访问令牌,放在 Authorization: Bearer 里调用接口。 |
| captcha_code | string | — | 图形验证码上显示的字符。 |
| captcha_id | string | — | 图形验证码 id,来自 GET /auth/captcha;连续登录失败后必填。 |
| channel | string | 必填 | 按邮箱还是手机号找回。 |
| code | string | 必填 | 发到 target 的验证码(POST /verify-codes,purpose=reset_password)。 |
| expires_in | integer | — | access token 有效秒数。 |
| id | string | — | 登录时作为 captcha_id 回传;一次性,验一次即作废(不论对错)。 |
| image | string | — | PNG 的 data URI。 |
| key | string | — | base32 密钥(只在这里返回一次)。 |
| must_change_password | boolean | — | 只在登录响应里出现;true = 该账号还在用装机生成的初始口令(/root/gocdn-admin.pass),须先改口令(PUT /auth/password)再用,改过后不再出现。 |
| new_password | string | 必填 | 新口令,8 到 128 个字符。 |
| old_password | string | 必填 | 原口令。 |
| otpauth_uri | string | — | otpauth:// 地址,用认证器 App 扫码添加。 |
| password | string | 必填 | 登录口令。 |
| recovery_codes | string[] | — | 8 个一次性恢复码(XXXXX-XXXXX),只在启用成功时返回这一次。 |
| refresh_token | string | — | 刷新令牌,用来换新的一对令牌。 |
| sso_ticket | string | 必填 | 超管签发的登录票:licwire 信封(kind sso_ticket)字节的 base64url(无填充)。 |
| switch_ticket | string | 必填 | 管理员换到的一次性切换票。 |
| target | string | 必填 | 账号绑定的邮箱或手机号。 |
| token_type | string | — | 令牌类型,固定为 Bearer。 |
| totp_code | string | — | 动态口令(TOTP)的 6 位当前码,或一个未用过的恢复码(XXXXX-XXXXX,用后作废);账号启用动态口令时必填。 |
| user_id | integer | 必填 | 用户 ID |
| username | string | 必填 | 用户名 |
| verify_code | string | — | 登录二次验证码。账号开了邮件/短信验证码登录(login_verify)时必填,先经 POST /verify-codes(purpose=login)获取。 |