Create an identity

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

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

{
  "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. Recommended prefix is `idn_`.
`external_id`	string	End-user ID from the integrator’s system.
`name`	string	Display name.
`enabled`	boolean	Whether the Identity can be used for new operations.
`metadata`	object	Custom metadata.
`created_at`	string	Creation timestamp.
`updated_at`	string	Update timestamp.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Missing or invalid `external_id`, `name`, or metadata.
401	`authentication_error`	PAT invalid or expired.
409	`conflict_error`	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.

Create an identity

Headers

Body parameters

Example request

Example response

Response fields

Errors

Notes

List identities

Create a session

​Headers

​Body parameters

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

List identities

Create a session

Headers

Body parameters

Example request

Example response

Response fields

Errors

Notes

Related