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

# 更新 Identity

> 更新 Forward Identity 基础信息。

`POST /api/v1/forward/identities/{identity_id}`

只更新请求体中出现的字段。`metadata` 为合并更新，空字符串 value 表示删除对应 key。

## 请求头

| Header          | 是否必填 | 说明                 |
| --------------- | ---- | ------------------ |
| Authorization   | 是    | `Bearer <PAT>`     |
| Content-Type    | 是    | `application/json` |
| Idempotency-Key | 否    | 有副作用请求可选的幂等键。      |

## 路径参数

| 参数           | 类型     | 是否必填 | 说明                   |
| ------------ | ------ | ---- | -------------------- |
| identity\_id | string | 是    | Forward Identity ID。 |

## 请求体参数

| 参数           | 类型      | 是否必填 | 说明                             |
| ------------ | ------- | ---- | ------------------------------ |
| external\_id | string  | 否    | 替换原有终端用户 ID。                   |
| name         | string  | 否    | 替换展示名。                         |
| enabled      | boolean | 否    | 更新 Identity 是否可用。              |
| metadata     | object  | 否    | 合并更新业务元数据；空字符串 value 删除对应 key。 |

## 示例请求

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/identities/idn_019eabc123' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example User",
  "enabled": false,
  "metadata": {
    "channel": "app"
  }
}'
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "id": "idn_019eabc123",
  "external_id": "user_456",
  "name": "Example User",
  "enabled": false,
  "metadata": {
    "channel": "app"
  },
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}
```

## 响应字段

| 字段  | 类型     | 说明                |
| --- | ------ | ----------------- |
| 返回值 | object | 更新后的 Identity 对象。 |

## 错误

| HTTP | Type                    | Code                      | 触发条件              |
| ---- | ----------------------- | ------------------------- | ----------------- |
| 400  | `invalid_request_error` | -                         | 请求体不合法。           |
| 404  | `not_found_error`       | -                         | Identity 不存在。     |
| 409  | `conflict_error`        | -                         | Identity 与已有记录冲突。 |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。       |

## 注意事项

* `enabled=false` 会阻止后续需要 active Identity 的新操作。
* 历史 Session 和审计记录不会被修改。

## 相关

<CardGroup cols={2}>
  <Card title="获取 Identity" icon="file-lines" href="/cloud-agents/api/forward/identities/get" />

  <Card title="删除 Identity" icon="trash" href="/cloud-agents/api/forward/identities/delete" />
</CardGroup>