Create an end-user identity for Forward API usage.
POST /api/v1/forward/identities
Creates an Identity that represents one end user in the integrator's product. Forward uses the Identity to scope sessions, configuration, resources, and audit context.
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT or SAT> |
Content-Type | Yes | application/json |
Idempotency-Key | No | Optional idempotency key for unsafe requests. |
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
external_id | string | Yes | End-user ID from the integrator's system. Must not be empty or whitespace only. |
name | string | No | Display name. Must not be empty or whitespace only when provided. |
enabled | boolean | No | Whether this identity can be used. Defaults to true. |
metadata | object | No | Custom metadata. Recommended maximum 16 keys. |
Example request
Example response
HTTP 201 Created
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Forward Identity ID. Recommended prefix is idn_. |
external_id | string | End-user ID from the integrator's system. |
name | string | Display name. |
identity_type | string | Identity type. A standard Identity returns normal. |
enabled | boolean | Whether the Identity can be used for new operations. |
metadata | object | Custom metadata. |
created_at | string | Creation time in RFC 3339 format. |
updated_at | string | Most recent update time in RFC 3339 format. |
Errors
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | - | Missing or invalid external_id, name, or metadata. |
| 401 | authentication_error | authentication_required | The PAT or SAT is invalid or expired. |
| 409 | conflict_error | - | The Identity conflicts with an existing record. |
Notes
- Identity is not a Qoder login account or IAM user.
- The integrator remains responsible for authenticating the real end user.