API 认证

使用 JWT Bearer 令牌或 API 密钥认证 sh0 REST API，实现编程访问。

获取 API 令牌

要获取 JWT 令牌，使用您的凭证向登录端点发送 POST 请求：

Terminal

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

如果凭证有效，API 返回 JWT 令牌和用户信息：

Response (200 OK)

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJjMTIzIiwiZXhwIjoxNzE...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "Admin",
      "role": "admin"
    }
  }
}

如果启用了双因素认证，请包含 TOTP 验证码：

Terminal

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

显示凭证交换获取 JWT 令牌的 API 登录流程图

Bearer 令牌认证

在每个 API 请求的 Authorization 头中包含 JWT 令牌：

Terminal

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

令牌包含用户 ID、角色和过期时间。sh0 在每个请求上验证签名和过期时间。

Tip

安全存储令牌。在脚本中，使用环境变量而非硬编码令牌：

Terminal

export SH0_TOKEN="eyJhbGciOiJIUzI1NiIs..."

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

API 密钥替代方案

对于长期运行的集成（CI/CD 流水线、监控脚本、Webhook），API 密钥比 JWT 令牌更实用，因为它们不会过期。

创建 API 密钥：

在控制台中导航至 Settings → API Keys。
点击 Generate API Key。
输入描述性名称（例如"CI/CD Pipeline"或"Monitoring"）。
立即复制密钥——仅显示一次。

API 密钥管理面板及生成的密钥

使用 API 密钥：

Terminal

curl https://your-server:9000/api/apps \
  -H "X-API-Key: sh0_key_abc123def456"

Warning

API 密钥拥有与创建者相同的权限。像对待密码一样对待它们——永远不要将其提交到版本控制或以明文形式共享。

令牌过期与刷新

JWT 令牌默认有效期为 30 天。过期时间编码在令牌负载中。

要刷新即将过期的令牌，使用当前（仍然有效的）令牌调用刷新端点：

Terminal

curl -X POST https://your-server:9000/api/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

Response (200 OK)

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(new token)...",
    "expires_at": "2026-04-20T12:00:00Z"
  }
}

控制台在令牌过期前自动刷新。对于 API 集成，请实现令牌刷新逻辑或使用 API 密钥以避免过期问题。

Note

API 密钥不会过期。它们在手动撤销之前一直有效，可在 Settings → API Keys 中管理。

控制台请求的 CSRF 令牌

从控制台（浏览器）发起请求时，sh0 使用 CSRF 令牌防止跨站请求伪造攻击。这由控制台的 API 客户端自动处理。

如果您构建自定义前端并通过 Cookie（而非 Bearer 令牌）进行认证，您需要在请求中包含 CSRF 令牌：

Terminal

# Get a CSRF token
curl https://your-server:9000/api/auth/csrf-token \
  -H "Cookie: session=..."

# Include it in state-changing requests
curl -X POST https://your-server:9000/api/apps \
  -H "Cookie: session=..." \
  -H "X-CSRF-Token: csrf_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Tip

Bearer 令牌认证（通过 Authorization 头）不需要 CSRF 令牌。CSRF 保护仅适用于基于 Cookie 的会话。

认证错误

认证失败时，API 返回结构化的错误响应：

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

常见错误场景：

状态	代码	原因
401	`UNAUTHORIZED`	缺失、无效或过期的令牌/API 密钥
401	`INVALID_CREDENTIALS`	登录时邮箱或密码错误
401	`TOTP_REQUIRED`	已启用双因素认证但未提供 TOTP 验证码
403	`FORBIDDEN`	用户角色没有此操作的权限
429	`RATE_LIMITED`	登录尝试过多（每 IP 每分钟 5 次）

API 浏览器中的认证错误响应

Commands Reference

Quick Start