清理 Identity 当前会影响未来会话的配置、入口和绑定资源。
POST /api/v1/forward/identities/{identity_id}/clear
清理后 Identity 本身仍然保留，可以继续创建新的会话。新的会话不会继续使用清理前的相关配置、定时任务和资源绑定；历史会话保持归档状态。
请求头
| Header | 是否必填 | 说明 |
|---|---|---|
| Authorization | 是 | Bearer <PAT 或 SAT> |
| Content-Type | 否 | 请求体非空时使用 application/json。 |
路径参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| identity_id | string | 是 | Forward Identity ID。 |
请求体参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| reason | string | 否 | 清理原因，仅用于记录调用意图。 |
示例请求
示例响应
HTTP 200 OK
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| identity_id | string | 被清理的 Identity ID。 |
| status | string | 清理状态，成功时为 completed。 |
| completed_at | string | Forward 侧清理完成时间，使用 RFC 3339 格式。 |
| summary.identity_configs_archived | number | 本次处理的 Identity Config 数量。 |
| summary.resource_bindings_archived | number | 本次处理的资源绑定数量。 |
| summary.identity_owned_resources_archived | number | 本次处理的 Identity 资源数量（Forward 侧归属登记）。 |
| summary.schedules_archived | number | 本次处理的 Schedule 数量。 |
| summary.schedule_runs_skipped | number | 本次跳过的待执行 Schedule Run 数量。 |
| summary.sessions_archived | number | 本次处理的 Session 数量。 |
错误
| HTTP | Type | Code | 触发条件 |
|---|---|---|---|
| 400 | invalid_request_error | - | 请求体格式或参数不合法。 |
| 401 | authentication_error | authentication_required | PAT 或 SAT 无效、过期或缺失。 |
| 404 | not_found_error | - | Identity 不存在或当前调用方不可见。 |
| 409 | conflict_error | ADMIN_IDENTITY_READ_ONLY 或 - | Admin Identity 只读，或该 Identity 存在正在运行的 Schedule Run。 |
Identity 归属资源的清理
清理会处理该 Identity 名下的归属资源，不同类型的处理方式不同：
| 资源类型 | 处理方式 |
|---|---|
| Environment | 归档，不删除 |
| Vault | 先逐个归档其下所有生效中的 Credential，再归档 Vault |
| Skill | 删除资源，并归档 Forward 侧归属记录 |
| File | 删除资源，并归档 Forward 侧归属记录 |
| Memory Store | 按既有语义处理 |
completed。清理操作会有限重试并逐资源记录日志。
内部目录状态与资源清理不在同一个分布式事务中。部分失败时接口返回错误，但已经提交的 Forward 归档以及已经完成的归档或删除不会自动回滚；应根据逐资源日志处理失败项。Skill/File 是删除而非归档，回滚 Forward 服务版本不会恢复已经删除的资源。
仅归档 Vault 不视为完成：必须先归档其下全部生效中的 Credential。Credential 列表分页读取，直到没有生效中的 Credential 为止。Skill 与 File 则执行删除。
备注
- 该接口不会删除 Identity 本体。
- 清理后可以继续创建新的 Session、配置和 Schedule。
- 重复调用不会恢复已处理的资源或配置。