> ## 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 终端用户身份。

`POST /api/v1/forward/identities`

Identity 表示集成方产品中的一个 C 端用户，Forward 用它来收敛 Session、配置、资源和审计上下文。

## 请求头

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

## 请求体参数

| 参数           | 类型      | 是否必填 | 说明                        |
| ------------ | ------- | ---- | ------------------------- |
| external\_id | string  | 是    | 集成方系统中的终端用户 ID，不能是空串或纯空白。 |
| name         | string  | 否    | 展示名，传入时不能是空串或纯空白。         |
| enabled      | boolean | 否    | 是否启用该 Identity，默认 `true`。 |
| metadata     | object  | 否    | 业务元数据，建议最多 16 个 key。      |

## 示例请求

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

## 示例响应

**HTTP 200 OK**

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

## 响应字段

| 字段           | 类型      | 说明                               |
| ------------ | ------- | -------------------------------- |
| id           | string  | Forward Identity ID，建议前缀 `idn_`。 |
| external\_id | string  | 集成方系统中的终端用户 ID。                  |
| enabled      | boolean | 是否允许继续使用该 Identity。              |
| metadata     | object  | 业务元数据。                           |

## 错误

| HTTP | Type                    | Code                      | 触发条件                                 |
| ---- | ----------------------- | ------------------------- | ------------------------------------ |
| 400  | `invalid_request_error` | -                         | `external_id`、`name` 或 metadata 不合法。 |
| 409  | `conflict_error`        | -                         | Identity 与已有记录冲突。                    |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。                          |

## 注意事项

* Identity 不是 Qoder 登录账号，也不是 IAM user。
* 真实终端用户认证仍由集成方负责。

## 相关

<CardGroup cols={2}>
  <Card title="列出 Identities" icon="list" href="/cloud-agents/api/forward/identities/list" />

  <Card title="创建 Session" icon="comment" href="/cloud-agents/api/forward/sessions/create" />
</CardGroup>