For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /api/authentication.md.
  • 简体中文
  • 对 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 发送到登录端点:

    cURL
    Python
    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>"}'

    提取访问令牌

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

    {
      "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "role": "admin",
      "user": {
        "id": 1,
        "username": "admin",
        "display_name": "Administrator"
      }
    }

    在 Authorization 头中传递令牌

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

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

    登录请求字段

    usernamestringbody必填

    本地用户名或邮箱。启用 LDAP 且本地密码不匹配时,会用同一对字段再向目录验证。

    passwordstringbody必填

    本地密码;若走 LDAP,则为目录密码。

    captcha_tokenstringbody

    启用强校验验证码(turnstile、hcaptcha、recaptcha、recaptcha-v3 或 tencent)时必填。最长 4096 个字符。tencent 请把回调对写成 ticket:randstr。默认 slider 只用于页面,API 不会校验。

    登录响应字段

    access_tokenstring

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

    rolestring

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

    userobject

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

    user 字段
    user.idinteger

    用户的唱一数字标识符。

    user.usernamestring

    账户的登录用户名。

    user.display_namestring

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

    令牌过期

    令牌默认在 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,以及 SSO 字段:sso_identities(已绑定的 {kind})、sso_linked、sso_kind(第一个已绑定类型)和 has_password。

    修改密码

    无需管理员介入,自行修改密码:

    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)。

    登录验证码

    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 等目录。用户仍在原有用户名/密码框登录:先尝试验证本地密码,再回退到目录。

    LDAP 目录登录

    LDAP

    常见步骤:填写服务器地址(优先 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 剩余不足三分之二时会续期一次。

    验证器和所有通行密钥都用不了时,在服务器上清掉这些因子,不改密码:

    octop user reset-mfa <用户名>

    OpenID Connect

    页面提供 Azure AD、Google、Keycloak 与 Okta 快速开始预设。选择预设可填入常用 scope,再填写签发者 URL 与 OAuth 客户端凭据,并把生成的回调地址复制到身份提供商中。点击测试连接前请先保存;Octop 会测试已保存的发现配置。

    方法路径谁可以调用作用
    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管理员测试能否连上身份提供方

    飞书、钉钉与企业微信

    在用户页的对应标签中配置飞书、钉钉、企业微信和 OIDC。填写 OAuth 客户端 ID 与密钥,把生成的回调地址复制到提供方控制台,保存后再点测试连接。企业微信还需要 extra.agent_id。

    已登录用户可以绑定或解绑这些身份。解绑最后一个登录方式时,必须先有本地密码。

    方法路径谁可以调用作用
    GET/auth/oauth/status任何人{providers:[{kind, display_name, enabled}]}
    POST/auth/oauth/start任何人请求体 {kind, redirect_after?} → 授权 URL(kind 为 oidc、feishu、dingtalk 或 wecom)
    GET/auth/oauth/callback任何人提供方回调(code,钉钉为 authCode)
    POST/auth/oauth/exchange任何人与 /auth/oidc/exchange 相同的一次性兑换
    POST/auth/oauth/bind/start用户把该身份绑定到当前用户
    POST/auth/oauth/unbind用户按 kind 解绑一个 SSO 身份
    GET/auth/oauth/providers/{kind}sso读取提供方配置;不返回 client_secret
    PUT/auth/oauth/providers/{kind}sso写入提供方配置;client_secret 只写不读
    POST/auth/oauth/providers/{kind}/testsso测试提供方凭据

    通过 SSO 新建的账号是普通用户。如果他们需要改设置,再单独授权。OIDC 提供方仍可使用旧的 /auth/oidc/config 路由。

    兑换邀请

    持有邀请链接的人可以调用这些接口。管理员在管理 → 用户中创建邀请,或调用 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 UnauthorizedAUTH_FAILED登录时提交的凭据无效检查用户名和密码
    401 UnauthorizedTOKEN_EXPIREDJWT 已超过其 TTL重新登录以获取新令牌
    403 ForbiddenFORBIDDEN已认证但角色权限不足(例如非管理员访问管理员端点)用具备所需角色的账户登录
    403 ForbiddenUSER_DISABLED账户已被管理员禁用联系您的 Octop 管理员
    423 LockedLOGIN_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 界面交互式探索每个端点——无需额外工具。