> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

## 登录并获取令牌

**1. POST 您的凭据**

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

```bash cURL theme={null}
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 theme={null}
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"]
```

**2. 提取访问令牌**

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

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "admin",
  "user": {
    "id": 1,
    "username": "admin",
    "display_name": "Administrator"
  }
}
```

**3. 在 Authorization 头中传递令牌**

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

```bash cURL theme={null}
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <your_token>'
```

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

### 登录请求字段

**username** `string` *required*

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

**password** `string` *required*

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

### 登录响应字段

**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` 获取新令牌。

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

## 获取当前用户信息

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

```bash theme={null}
curl http://127.0.0.1:8088/api/auth/me \
  -H 'Authorization: Bearer <token>'
```

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

## 修改密码

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

```bash theme={null}
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`。详见[用户与管理](https://octop.mintlify.site/zh/api/users-admin.md)。

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

## 退出登录

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

```bash theme={null}
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` |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.