Skip to main content
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>
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.
metadataobjectNoCustom 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

FieldTypeDescription
idstringForward Identity ID. Recommended prefix is idn_.
external_idstringEnd-user ID from the integrator’s system.
namestringDisplay name.
enabledbooleanWhether the Identity can be used for new operations.
metadataobjectCustom metadata.
created_atstringCreation timestamp.
updated_atstringUpdate timestamp.

​
Errors

HTTPTypeTrigger
400invalid_request_errorMissing or invalid external_id, name, or metadata.
401authentication_errorPAT invalid or expired.
409conflict_errorIdentity 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.

List identities

Create a session