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

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

#登录并获取令牌

curl -X POST http://127.0.0.1:8088/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "<your_username>", "password": "<your_password>"}'

import requests

resp = requests.post(
    "http://127.0.0.1:8088/api/auth/login",
    json={"username": "<your_username>", "password": "<your_password>"},
)
token = resp.json()["access_token"]

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

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

headers = {"Authorization": f"Bearer {token}"}
agents = requests.get(
    "http://127.0.0.1:8088/api/agents",
    headers=headers,
).json()

#登录请求字段

#登录响应字段

#令牌过期

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

#获取当前用户信息

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

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——进程没起来之前页面不可用。

#单点登录

管理员在管理 → 用户 → 单点登录中启用 SSO。实例上已有用户后，登录页可以为每个已启用的提供方显示使用 {name} 继续。

#OpenID Connect

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

#飞书、钉钉与企业微信

同一单点登录面板也可以配置飞书、钉钉和企业微信。填写 OAuth 客户端 ID 与密钥，把生成的回调地址复制到提供方控制台，保存后再点测试连接。企业微信还需要 extra.agent_id。

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

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

#兑换邀请

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

#退出登录

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

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

成功响应返回 204 No Content。

#错误参考