对 Octop API 的所有请求进行认证与授权
除 /api/health、/api/setup/*、/api/auth/captcha、公开的 SSO 启动/回调/兑换、邀请兑换和 OpenAPI 模式外,每个 Octop API 调用都需要 JWT 访问令牌。通过凭据登录获取令牌,然后在后续每个请求的 Authorization 头中包含它。令牌默认 24 小时后过期;重新登录即可获取新令牌。
首次登录凭据取决于安装方式。裸机 octop init / 设置向导:到用户主目录打开 ~/octop-login.txt 读取一次性设置密码,再用您自设的管理员用户名和密码登录。Docker 首次启动:用户名为 admin(可用 OCTOP_ADMIN_USERNAME 覆盖),密码在 /data/.octop/credential.txt(docker exec octop cat /data/.octop/credential.txt);未设置 OCTOP_DEFAULT_PASSWORD 时会生成随机密码,弱密码会回退为随机密码。API 登录使用对应这套凭据。
登录并获取令牌
POST 您的凭据
将您的 username 和 password 发送到登录端点:
提取访问令牌
响应体包含您的 JWT 令牌以及角色和用户详情:
在 Authorization 头中传递令牌
在后续每个请求中将令牌作为 Bearer 凭证传递:
登录请求字段
本地用户名或邮箱。启用 LDAP 且本地密码不匹配时,会用同一对字段再向目录验证。
本地密码;若走 LDAP,则为目录密码。
启用强校验验证码(turnstile、hcaptcha、recaptcha、recaptcha-v3 或 tencent)时必填。最长 4096 个字符。tencent 请把回调对写成 ticket:randstr。默认 slider 只用于页面,API 不会校验。
登录响应字段
签名过的 JWT 令牌。将此值以 Bearer <access_token> 形式包含在 Authorization 头中。
账户的角色。为 "admin" 或 "user"。
已认证账户的基本资料信息。
user 字段
用户的唱一数字标识符。
账户的登录用户名。
在页面中显示的人类可读显示名称。
令牌过期
令牌默认在 24 小时后过期。使用环境变量 OCTOP_ACCESS_TOKEN_TTL(以秒为单位)控制此值。令牌过期后,重新调用 POST /api/auth/login 获取新令牌。
通过 octop admin rotate-jwt-secret 轮换 JWT 密钥会立即使所有待处理令牌失效。轮换后每个用户都必须重新登录。
获取当前用户信息
获取当前已认证用户的资料:
响应包含 id、username、role、display_name、locale,以及 SSO 字段:sso_identities(已绑定的 {kind})、sso_linked、sso_kind(第一个已绑定类型)和 has_password。
修改密码
无需管理员介入,自行修改密码:
成功响应返回 204 No Content。
新密码至少 8 位,须同时包含字母和数字,不能与当前密码相同,也不能是一小份常见弱口令列表中的值(例如 password123 或 admin123)。
登录验证码
GET /api/auth/captcha 返回登录控件所需的 {provider, site_key?}。该接口公开;首次设置尚未完成时返回 503。默认 provider 为 slider(只用于页面,API 不校验 token)。
启用强校验提供方后,POST /api/auth/login 必须带 captcha_token。验证码失败不会增加登录锁定次数。OIDC 与 OAuth 登录不走这项检查。
在管理 → 应用设置中配置,或使用 OCTOP_CAPTCHA_*(启动时快照,改环境变量后需重启)。GET / PUT /api/settings/captcha 需要 captcha 权限。GET 不返回密钥;PUT 时传空密钥会保留已保存的值。
如果设置里配错了强校验提供方导致所有人无法登录,运行 octop captcha reset 并重启 octop run。如果是启动环境变量 OCTOP_CAPTCHA_* 造成的,直接改磁盘上的 ~/.octop/env——进程没起来之前页面不可用。
登录方式
管理员在管理 → 用户各标签页中配置登录方式。实例上已有用户后,登录页可以为每个已启用的 OAuth 提供方显示使用 {name} 继续。
LDAP 目录登录
在管理 → 用户 → LDAP中接入 Active Directory、OpenLDAP 等目录。用户仍在原有用户名/密码框登录:先尝试验证本地密码,再回退到目录。

常见步骤:填写服务器地址(优先 ldaps://)、服务账号、检索基准与 {username} 过滤器、可选管理员组,然后保存并测试连接,最后启用 LDAP。按目录组映射角色只在建号时生效,之后组变更不会悄悄提权。
主机名或公网地址必须使用 ldaps://,或 ldap:// 加 StartTLS。字面量内网或回环地址(10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8、::1)可以明文 ldap://。页面会提示口令将明文传输。
关闭自动建号后,要先在用户管理里创建目录账号,对方才能登录。用户名须与目录登录名一致,且不设本地密码。这时 POST /api/auth/change-password 返回 400 PASSWORD_NOT_SET。目录不可达时返回 502 LDAP_UNAVAILABLE(若本地密码已匹配则仍按本地结果处理)。还没建号的目录用户会得到 403 LDAP_USER_NOT_PROVISIONED。
账户安全
打开账户安全,在密码之后再加一道检查。可以用验证器应用、通行密钥、恢复码,也可以几种一起开。
登录页的通行密钥登录默认关闭。管理员要在应用设置 → 通行密钥里打开登录页显示「使用通行密钥登录」。已经添加的通行密钥仍可作为二次验证。通行密钥需要 HTTPS,或 http://localhost,不能用 127.0.0.1 这类 IP。
GET /auth/passkey/status 为登录页返回 {passwordless_login}。管理员用 GET 和 PUT /settings/webauthn 读写 Relying Party 设置。
修改密码会使尚未过期的访问令牌失效。POST /auth/change-password 在响应头 X-Octop-Access-Token 里返回新令牌。会话在 OCTOP_ACCESS_TOKEN_TTL 剩余不足三分之二时会续期一次。
验证器和所有通行密钥都用不了时,在服务器上清掉这些因子,不改密码:
OpenID Connect
页面提供 Azure AD、Google、Keycloak 与 Okta 快速开始预设。选择预设可填入常用 scope,再填写签发者 URL 与 OAuth 客户端凭据,并把生成的回调地址复制到身份提供商中。点击测试连接前请先保存;Octop 会测试已保存的发现配置。
飞书、钉钉与企业微信
在用户页的对应标签中配置飞书、钉钉、企业微信和 OIDC。填写 OAuth 客户端 ID 与密钥,把生成的回调地址复制到提供方控制台,保存后再点测试连接。企业微信还需要 extra.agent_id。
已登录用户可以绑定或解绑这些身份。解绑最后一个登录方式时,必须先有本地密码。
通过 SSO 新建的账号是普通用户。如果他们需要改设置,再单独授权。OIDC 提供方仍可使用旧的 /auth/oidc/config 路由。
兑换邀请
持有邀请链接的人可以调用这些接口。管理员在管理 → 用户中创建邀请,或调用 POST /api/users/invites。详见用户与管理。
退出登录
在服务器端使当前令牌失效:
成功响应返回 204 No Content。
错误参考
设置 OCTOP_ENABLE_API_DOCS=1(或在 config.json 中设置 "enable_api_docs": true)并访问 http://127.0.0.1:8088/api/docs,可以使用内置的 Scalar 界面交互式探索每个端点——无需额外工具。

