Update an identity

Update a Forward identity.

POST /api/v1/forward/identities/{identity_id}

Updates mutable Identity fields. Omitted fields are unchanged. metadata is merged; a metadata value of an empty string deletes that key.

Headers

Header	Required	Description
Authorization	Yes	Bearer <PAT>
Content-Type	Yes	application/json
Idempotency-Key	No	Optional idempotency key for unsafe requests.

Path parameters

Parameter	Type	Required	Description
identity_id	string	Yes	Forward Identity ID.

Body parameters

Parameter	Type	Required	Description
external_id	string	No	Replaces the existing end-user ID.
name	string	No	Replaces the display name.
enabled	boolean	No	Updates whether the Identity can be used.
metadata	object	No	Merge updates custom metadata. Empty string values delete keys.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/identities/idn_019eabc123' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example User",
    "enabled": false,
    "metadata": {
      "channel": "app"
    }
  }'

Example response

HTTP 200 OK

{
  "id": "idn_019eabc123",
  "external_id": "user_456",
  "name": "Example User",
  "enabled": false,
  "metadata": {
    "channel": "app"
  },
  "created_at": "2026-06-18T10:00:00Z",
  "updated_at": "2026-06-18T10:30:00Z"
}

Response fields

Returns the updated Identity object.

Errors

HTTP	Type	Trigger
400	invalid_request_error	Invalid request body.
401	authentication_error	PAT invalid or expired.
404	not_found_error	Identity does not exist.
409	conflict_error	Identity conflicts with an existing record.

Notes

• enabled=false prevents new operations that require an active Identity.
• Historical sessions and audit records are not modified.

Related

Get an identity

Delete an identity