> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 对 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` 发送到登录端点：

```bash 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>"}'
```
```python Python
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"]
```


### 提取访问令牌

响应体包含您的 JWT 令牌以及角色和用户详情：
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "admin",
  "user": {
    "id": 1,
    "username": "admin",
    "display_name": "Administrator"
  }
}
```

### 在 Authorization 头中传递令牌

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

```bash cURL
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <your_token>'
```
```python Python
headers = {"Authorization": f"Bearer {token}"}
agents = requests.get(
    "http://127.0.0.1:8088/api/agents",
    headers=headers,
).json()
```


### 登录请求字段


- `username` (string, body, 必填)

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


- `password` (string, body, 必填)

本地密码；若走 LDAP，则为目录密码。


- `captcha_token` (string, body)

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

### 登录响应字段


- `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 密钥会立即使**所有**待处理令牌失效。轮换后每个用户都必须重新登录。
> 


## 获取当前用户信息

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

```bash
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`。

## 修改密码

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

```bash
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 目录登录](/images/ui-ldap.png "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` 剩余不足三分之二时会续期一次。

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

```bash
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}/test` | `sso` | 测试提供方凭据                                                                               |

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

## 兑换邀请

持有邀请链接的人可以调用这些接口。管理员在**管理 → 用户**中创建邀请，或调用 `POST /api/users/invites`。详见[用户与管理](/api/users-admin.md)。

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

## 退出登录

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

```bash
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 界面交互式探索每个端点——无需额外工具。
> 

