对 Octop API 的所有请求进行认证与授权

通过 POST /api/auth/login 获取 JWT 访问令牌，然后在对 Octop REST API 的每个后续调用中将其作为 Bearer 令牌包含。

除 /api/health、/api/setup/* 和 OpenAPI 模式外，每个 Octop API 调用都需要 JWT 访问令牌。通过凭据登录获取令牌，然后在后续每个请求的 Authorization 头中包含它。令牌默认 24 小时后过期；重新登录即可获取新令牌。

首次登录凭据取决于安装方式。裸机 octop init / 设置向导：到用户主目录打开 ~/octop-login.txt 读取一次性设置密码，再用您自设的管理员用户名和密码登录。Docker 首次启动：默认 admin / Octop123（同时写入 /data/.octop/credential.txt），除非您设置了 OCTOP_ADMIN_USERNAME / OCTOP_DEFAULT_PASSWORD。API 登录使用对应这套凭据。

​

登录并获取令牌

1. POST 您的凭据

   将您的 username 和 password 发送到登录端点：

   cURL

   curl -X POST http://127.0.0.1:8088/api/auth/login \
     -H 'Content-Type: application/json' \
     -d '{"username": "<your_username>", "password": "<your_password>"}'
   
2. 提取访问令牌

   响应体包含您的 JWT 令牌以及角色和用户详情：

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "role": "admin",
     "user": {
       "id": 1,
       "username": "admin",
       "display_name": "Administrator"
     }
   }
   
3. 在 Authorization 头中传递令牌

   在后续每个请求中将令牌作为 Bearer 凭证传递：

   cURL

   curl http://127.0.0.1:8088/api/agents \
     -H 'Authorization: Bearer <your_token>'
   

​

登录请求字段

username · string · 必填

账户用户名。使用您在设置向导中创建的用户名（或之后通过用户管理创建的账户）。

password · string · 必填

账户密码。使用您在设置向导中设置的密码（或之后重置的密码）。

​

登录响应字段

access_token · string

签名过的 JWT 令牌。将此值以 Bearer <access_token> 形式包含在 Authorization 头中。

role · string

账户的角色。为 "admin" 或 "user"。

user · object

已认证账户的基本资料信息。

显示 user 字段

user.id · integer

用户的唱一数字标识符。

user.username · string

账户的登录用户名。

user.display_name · string

在页面中显示的人类可读显示名称。

​

令牌过期

令牌默认在 24 小时后过期。使用环境变量 OCTOP_ACCESS_TOKEN_TTL（以秒为单位）控制此值。令牌过期后，重新调用 POST /api/auth/login 获取新令牌。

通过 octop admin rotate-jwt-secret 轮换 JWT 密钥会立即使所有待处理令牌失效。轮换后每个用户都必须重新登录。

​

获取当前用户信息

获取当前已认证用户的资料：

curl http://127.0.0.1:8088/api/auth/me \
  -H 'Authorization: Bearer <token>'

响应包含 id、username、role、display_name、locale 等其他资料字段。

​

修改密码

无需管理员介入，自行修改密码：

curl -X POST http://127.0.0.1:8088/api/auth/change-password \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"old_password": "octop", "new_password": "mysecurepass1"}'

成功响应返回 204 No Content。

新密码至少 8 位，须同时包含字母和数字，不能与当前密码相同，也不能是一小份常见弱口令列表中的值（例如 password123 或 admin123）。

​

OpenID Connect

管理员在管理 → 用户 → 单点登录中启用 OIDC。实例上已有用户后，登录页可以显示使用 {name} 继续。

方法	路径	谁可以调用	作用
GET	/auth/oidc/status	任何人	SSO 是否开启，以及按钮名称
POST	/auth/oidc/start	任何人	开始身份提供方登录
GET	/auth/oidc/callback	任何人	从身份提供方返回
POST	/auth/oidc/exchange	任何人	完成登录，返回与密码登录相同的 JWT
GET	/auth/oidc/config	管理员	读取 SSO 设置（密钥不会返回）
PUT	/auth/oidc/config	管理员	保存 SSO 设置
POST	/auth/oidc/config/test	管理员	测试能否连上身份提供方

通过 SSO 新建的账号是普通用户。如果他们需要改设置，再单独授权。

​

兑换邀请

持有邀请链接的人可以调用这些接口。管理员在管理 → 用户中创建邀请，或调用 POST /api/users/invites。详见用户与管理。

方法	路径	作用
POST	/auth/invite/validate	检查邀请码是否仍有效
POST	/auth/invite/redeem	创建用户并返回 JWT

​

退出登录

在服务器端使当前令牌失效：

curl -X POST http://127.0.0.1:8088/api/auth/logout \
  -H 'Authorization: Bearer <token>'

成功响应返回 204 No Content。

​

错误参考

HTTP 状态码	错误代码	原因	解决方法
401 Unauthorized	AUTH_FAILED	登录时提交的凭据无效	检查用户名和密码
401 Unauthorized	TOKEN_EXPIRED	JWT 已超过其 TTL	重新登录以获取新令牌
403 Forbidden	FORBIDDEN	已认证但角色权限不足（例如非管理员访问管理员端点）	用具备所需角色的账户登录
403 Forbidden	USER_DISABLED	账户已被管理员禁用	联系您的 Octop 管理员
423 Locked	LOGIN_LOCKED	登录失败次数过多，账户已锁定	等待锁定期结束，或请管理员调用 POST /api/users/{id}/unlock-login

设置 OCTOP_ENABLE_API_DOCS=1（或在 config.json 中设置 "enable_api_docs": true）并访问 http://127.0.0.1:8088/api/docs，可以使用内置的 Scalar 界面交互式探索每个端点——无需额外工具。