Skip to main content
Identities

Create an identity

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

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Body parameters

ParameterTypeRequiredDescription
external_idstringYesEnd-user ID from the integrator's system. Must not be empty or whitespace only.
namestringNoDisplay name. Must not be empty or whitespace only when provided.
enabledbooleanNoWhether this identity can be used. Defaults to true.
auto_memory_storeboolean|nullNoWhether to automatically create a default Memory Store on demand when creating a Session. Omitted or null means true; false disables automatic creation. You can change this with Update an identity.
metadataobjectNoCustom metadata. Recommended maximum 16 keys.

Example request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/identities' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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",
  "identity_type": "normal",
  "enabled": true,
  "auto_memory_store": true,
  "metadata": {
    "channel": "web"
  },
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:00:00Z"
}

Response fields

FieldTypeDescription
idstringForward Identity ID. Recommended prefix is idn_.
external_idstringEnd-user ID from the integrator's system.
namestringDisplay name.
identity_typestringIdentity type. A standard Identity returns normal.
enabledbooleanWhether the Identity can be used for new operations.
auto_memory_storebooleanWhether to automatically create a default Memory Store. Defaults to true.
metadataobjectCustom metadata.
created_atstringCreation time in RFC 3339 format.
updated_atstringMost recent update time in RFC 3339 format.

Errors

HTTPTypeCodeTrigger
400invalid_request_error-Invalid request body parameters.
401authentication_error-The PAT or SAT is invalid or expired.
409conflict_error-The Identity conflicts with an existing record.

Notes

  • You can still explicitly mount a Memory Store when auto_memory_store=false.
  • Identity is not a Qoder login account or IAM user.
  • The integrator remains responsible for authenticating the real end user.

List identities

Create a session