Replace an internal user's roles
/internal-users/{id}/rolesMakes the ids you send the internal user's roles and returns them; [] clears them. A role outside your own or global non-service roles is 422 exists (ids.N); a super-admin role not already held needs a super-admin caller (403 missing_permission). A SCIM-managed user is 409 scim_managed. Emits internal_user.updated (roles) when it changed; sends no email. Also accepts the deprecated {roleIds} body until 2027-06-30 (Deprecation, Sunset; not on a missing-scope 403), with dry run and idempotency. Sending the old ids 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 · InternalUserRoleReplace
Every role the internal user should hold, at most 500 distinct ids: your own organisation's or global roles, never service roles. A super-admin role not already held needs a super-admin caller. Send an empty list to clear them.
{
"ids": [
7,
12
]
}Responses
{
"data": [
{
"id": 7,
"name": "admin",
"label": "Administrator"
},
{
"id": 12,
"name": "compliance",
"label": "Compliance Officer"
}
]
}Authorization failed. error.code is one of org_disabled,
ip_blocked, missing_scope, scope_disabled, user_disabled.
The request conflicts with existing state (error.code = conflict),
e.g. a compliance flow with the requested name already exists.
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 PUT https://your-org-domain/kong/core/api/v2/internal-users/{id}/roles\
-H "Authorization: Bearer $HELM_API_KEY"\
-H "Content-Type: application/json"\
-d '{
"ids": [
7,
12
]
}'