API 认证

所有 REST 端点都位于 /api/v1 之下。脚本、CI 任务和集成使用 API 密钥进行身份验证；控制台使用 Cookie 会话。

API 密钥

API 密钥是唯一面向程序的凭据。请为每个工具单独创建一个，这样撤销某个集成时不会影响其他集成：

1. 在控制台中打开设置 → API 密钥，然后点击创建 API 密钥。
2. 为它起一个能说明用途的名字，例如“CI 流水线”。
3. 选择访问级别，并可按需设置过期日期。
4. 请立即复制密钥：它只显示一次，并以哈希形式存储。如果丢失，请删除并重新创建。

密钥以 sh0_ 开头。密钥的权限永远不会超过创建它的账户，并且密钥不能创建其他密钥。

访问级别

每个密钥带有三种访问级别之一，服务器会在每个请求上强制执行。通过 API 创建时，级别对应 scopes 字段：read、deploy 或 admin。

使用密钥

在每个请求的 Authorization: Bearer 请求头中发送密钥：

export SH0_TOKEN="sh0_..."
curl https://panel.example.com/api/v1/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

控制台会话

控制台通过 POST /api/v1/auth/login 登录。成功后，服务器设置 HttpOnly Cookie（sh0_access 和 sh0_refresh），并在响应体中返回 csrf_token；响应体中不返回任何令牌。此流程面向浏览器：脚本请使用 API 密钥。

访问会话有效期为 24 小时。控制台通过 POST /api/v1/auth/refresh 续期，该操作同时签发一个新的 30 天刷新会话；连续 30 天未使用的会话将结束。

修改密码会注销所有其他会话。登录尝试限制为每 15 分钟 5 次失败；输入正确的密码不计入限制。

双因素登录

当账户启用了双因素认证时，登录不会直接建立会话，而是返回 requires_totp 和一个短时有效的 totp_nonce。客户端随后将该 nonce 与 6 位验证码（或备用码）发送到 POST /api/v1/auth/totp/verify。验证限制为每 5 分钟 5 次。

CSRF 防护

通过会话 Cookie 认证的请求，在每个会修改状态的调用中都必须在 X-CSRF-Token 请求头中重复 CSRF 令牌。通过 Authorization 请求头中的 API 密钥认证的请求不需要它。

身份验证错误

错误使用标准错误结构。例如，未知或已撤销的密钥：

{"error":{"code":"UNAUTHORIZED","message":"Invalid API key"}}