Update an internal user
/internal-users/{id}Changes the fields you send and returns the internal user; omitted fields stay. status, sso_id and invite are read-only. A new email also rewrites the sign-in username; one another user holds returns 422 unique, one over 53 characters 422. A SCIM-managed user returns 409 scim_managed only when email, title, first_name or last_name changes; an email equal to the stored username or contact email counts as unchanged. Emits internal_user.updated and the legacy user.* events; sends no email. Sending the old values undoes it.
Path parameters
The internal user's id, a uuid. An unknown user, or one outside the token's organisation, returns 404.
Query parameters
Validate and run the call without committing it, returning what the real call would return with
meta.dry_runset.
Headers
Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.
Request body
application/json, required · InternalUserUpdate
The internal user's new email. At most 53 characters. Another user's email, in any case, returns 422
unique. It also rewrites the sign-in username. On a SCIM-managed user, an email equal to the stored one is not a change.Title, such as Mr, Ms or Dr. Null clears it.
The internal user's first name.
The internal user's last name.
The internal user's id in your own system.
{
"title": "Dr",
"first_name": "Augusta",
"last_name": "King",
"external_id": "HR-2026-0042"
}Responses
{
"data": {
"id": "6f1c2e8a-1b2c-4d5e-8f90-1a2b3c4d5e6f",
"first_name": "Augusta",
"last_name": "King",
"title": "Dr",
"email": "iris.stone@example.com",
"status": "active",
"external_id": "HR-1042",
"sso_id": null,
"invite": null,
"two_factor_enabled": true,
"last_login": "2026-06-16T09:12:00Z",
"created_at": "2026-06-15T10:30:00Z",
"updated_at": "2026-06-18T16:20:00Z"
}
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The user is provisioned by SCIM (error.code = scim_managed), so this
change must be made through the identity provider instead.
The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per
problem, or a code documented on the operation.
Examples
curl -X PATCH https://your-org-domain/kong/core/api/v2/internal-users/{id}\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"title": "Dr",
"first_name": "Augusta",
"last_name": "King",
"external_id": "HR-2026-0042"
}'