> ## 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.

# アイデンティティを作成する

> Forward API 利用のためのエンドユーザーアイデンティティを作成します。

`POST /api/v1/forward/identities`

インテグレーターの製品における 1 人のエンドユーザーを表す Identity を作成します。Forward はこの Identity を使用して、セッション、構成、リソース、監査コンテキストのスコープを定めます。

## Headers

| Header            | Required | Description              |
| ----------------- | -------- | ------------------------ |
| `Authorization`   | Yes      | `Bearer <PAT>`           |
| `Content-Type`    | Yes      | `application/json`       |
| `Idempotency-Key` | No       | 安全でないリクエストに対する任意のべき等性キー。 |

## Body parameters

| Parameter     | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `external_id` | string  | Yes      | インテグレーターのシステムにおけるエンドユーザー ID。空文字列や空白のみであってはなりません。 |
| `name`        | string  | No       | 表示名。指定する場合は空文字列や空白のみであってはなりません。                  |
| `enabled`     | boolean | No       | このアイデンティティが使用可能かどうか。デフォルトは `true`。               |
| `metadata`    | object  | No       | カスタムメタデータ。推奨される最大キー数は 16 です。                     |

## Example request

```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"
    }
  }'
```

## Example response

**HTTP 201 Created**

```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"
}
```

## Response fields

| Field         | Type    | Description                                  |
| ------------- | ------- | -------------------------------------------- |
| `id`          | string  | Forward Identity ID。推奨されるプレフィックスは `idn_` です。 |
| `external_id` | string  | インテグレーターのシステムにおけるエンドユーザー ID。                 |
| `name`        | string  | 表示名。                                         |
| `enabled`     | boolean | この Identity を新しい操作に使用できるかどうか。                |
| `metadata`    | object  | カスタムメタデータ。                                   |
| `created_at`  | string  | 作成タイムスタンプ。                                   |
| `updated_at`  | string  | 更新タイムスタンプ。                                   |

## Errors

| HTTP | Type                    | Trigger                                    |
| ---- | ----------------------- | ------------------------------------------ |
| 400  | `invalid_request_error` | `external_id`、`name`、またはメタデータが欠落しているか無効です。 |
| 401  | `authentication_error`  | PAT が無効または期限切れです。                          |
| 409  | `conflict_error`        | Identity が既存のレコードと競合しています。                 |

## Notes

* Identity は Qoder のログインアカウントや IAM ユーザーではありません。
* 実際のエンドユーザーの認証はインテグレーターの責任のままです。

## Related

<CardGroup cols={2}>
  <Card title="アイデンティティ一覧を取得する" icon="list" href="/cloud-agents/api/forward/identities/list" />

  <Card title="セッションを作成する" icon="comment" href="/cloud-agents/api/forward/sessions/create" />
</CardGroup>