---
url: /docs/api-docs/v1/admin/auth.md
---
# auth — adminLogin（3 action）

> 前缀：`/api/v1/admin/auth/`
> 代码：`src/app/admin/interface/api/auth.py` + `application/usecase/admin_login.py` + `admin_session.py`
> 权限：login 公开；me / logout 任意已登录 admin（`admin:me` / `admin:logout` — 三角色共享）

## 3.1.1 login —— 用户名密码登录

`POST /api/v1/admin/auth/login`

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `username` | string | ✅ | — | admin 账号（dev 种子：`admin` / `admin_ops` / `admin_it`） |
| `password` | string | ✅ | — | 密码（scrypt 哈希校验） |
| `clientId` | string | ⬜ | `admin-web` | 会话标识（透传 token 服务） |

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `tokens.access` | string | admin access token（后续 Bearer） |
| `tokens.refresh` | string | refresh token |
| `user.id` | string | admin id |
| `user.username` | string | 账号名 |
| `user.role` | string | `super` | `operator` | `it` |
| `user.status` | string | `active` | … |
| `user.email` | string | null | 邮箱 |
| `tokenExpiring` | bool | 恒 `false`（admin 无滚动续期） |

**错误码**：

| code | HTTP | 场景 |
|---|---|---|
| `40201501` | 200 | 用户名或密码错误（LOGIN\_FAILED） |
| `40201006` | 403 | 账号被封禁（USER\_BANNED） |

**dev 种子账号**：`admin/admin123`(super) · `admin_ops/ops12345`(operator) · `admin_it/it123456`(it)

## 3.1.2 logout —— 登出

`POST /api/v1/admin/auth/logout`（Bearer access）

**请求 body**：无（`ip` / `ua` 服务端从请求头采集）

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | bool | 恒 `true` |
| `audit_written` | bool | audit ADMIN\_LOGOUT 是否留痕（ADR-0010 必写） |

> P1 无状态 JWT 不做服务端撤销（P2 接 Redis 黑名单）；前端本地清 token 即完成登出。

## 3.1.3 me —— 当前 admin 信息

`GET /api/v1/admin/auth/me`（Bearer access）

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `admin.id` | string | admin id |
| `admin.username` | string | 账号名 |
| `admin.role` | string | 角色 |
| `admin.status` | string | 状态 |
| `admin.email` | string | null | 邮箱 |
| `admin.permissions` | string\[] | **RBAC 权限清单**（如 `["dashboard:read", "user:ban", …]`，由此驱动前端菜单显隐） |
| `admin.last_login_at` | string | null | ISO 时间 |

**错误码**：`40201002`（401）token 无效 / admin 不存在（如已删号）。