Update User

Updates a specified user.

Required Permissions

You need an administrator role or higher. However, you can update your own account directly even without administrator privileges. In this case, apart from name, email, title, department, phone, mobile, locale, home menu ID, API key, and password, all other fields — role, authentication mode, trusted IP addresses, idle session settings, login lockout settings, MFA settings, table and user group permissions, and so on — are silently ignored if you pass them, and the existing values are retained without an error (see below for the full list). You cannot update an account with a higher privilege level than your own.

HTTP Request

cURL Example

curl -H "Authorization: Bearer <API_KEY>" \
     -d login=jsmith \
     -d role_id=2 \
     -d name="John Smith" \
     -d idle_behavior=lock \
     -d idle_timeout=600 \
     -d email="john.smith@example.com" \
     -X PUT \
     https://HOSTNAME/api/sonar/users/bfd00bb0-be99-4fd5-8380-166f544975fa

Request Parameters

Path Parameters

Request Body Parameters

Role ID

• (1) Cluster administrator: User with all privileges including cluster administrator privileges.
• (2) Administrator: User with tenant privileges.
• (3) User: User with privileges to manage user objects such as dashboards, widgets, datasets, and tickets.
• (4) Dashboard Viewer: User with privileges to view dashboards, widgets, datasets, and tables only.

Password Policy

• Minimum 9 characters.
• Alphanumeric characters and special characters must be included.
• Any three identical consecutive characters are not allowed.

Success Response

{}

Error Responses

Required argument is missing

HTTP status code 400

{
  "error_code": "null-argument",
  "error_msg": "login should be not null"
}

Invalid argument length

HTTP status code 400

{
  "error_code": "invalid-argument",
  "error_msg": "'login' must be shorter than or equal to 255 characters."
}

Invalid login name format

HTTP status code 400. A login name must start with a letter, digit, period (.), or underscore (_), and the rest may also contain a hyphen (-).

{
  "error_code": "invalid-argument",
  "error_msg": "invalid login: user@name"
}

User identifier is not in valid GUID format

HTTP status code 400

{
  "error_code": "invalid-param-type",
  "error_msg": "guid should be guid type."
}

User is not found

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "user not found: bfd00bb0-be99-4fd5-8380-166f544975fa"
}

Duplicate login user name

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "duplicated user login: jsmith"
}

Invalid email format

HTTP status code 400

{
  "error_code": "invalid-argument",
  "error_msg": "'email' parameter is not a valid email address: foo"
}

No password specified for password authentication mode

HTTP status code 500. A password is required when an account that used external authentication only changes auth_mode to 0.

{
  "error_code": "illegal-state",
  "error_msg": "password should be not null"
}

Insufficient password complexity

Password validation runs inside the user update transaction. When it fails, the original error is rewrapped as a transaction failure and returned as 500 / illegal-state, and error_msg is prefixed with cannot update user, guid=<target user GUID> /. The following examples show each condition.

HTTP status code 500. The password contains the login name

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / password contains login name"
}

HTTP status code 500. The password is shorter than the minimum length

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / insufficient password length (minimum 9 characters)"
}

HTTP status code 500. The password exceeds the maximum length

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / password should not exceed maximum length (maximum 100 characters)"
}

HTTP status code 500. The password is missing a required character class (letter, digit, or special character)

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / password should include: alphabet, digit, special"
}

HTTP status code 500. The password repeats the same character three or more times in a row

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / password should not repeat same 3 characters"
}

Attempt to reuse a recent password

HTTP status code 500. The new password cannot match any of the previous passwords retained by old_passwd_count. For the reason described above, error_msg is prefixed with cannot update user, guid=<target user GUID> /.

{
  "error_code": "illegal-state",
  "error_msg": "cannot update user, guid=bfd00bb0-be99-4fd5-8380-166f544975fa / cannot-reuse-old-password"
}

Locale is not supported

HTTP status code 400

{
  "error_code": "invalid-argument",
  "error_msg": "unsupported locale: ru"
}

Invalid authentication mode

HTTP status code 400

{
  "error_code": "invalid-argument",
  "error_msg": "auth_mode should be 0 or 1. input is 2."
}

Update own role

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "cannot update role by yourself."
}

Update a user with higher privileges

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "no permission: cannot grant or modify cluster admin role by jsmith"
}

Role ID is not found

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "unknown role id: 5"
}

Menu ID is not found

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "unknown menu id: 0"
}

User group is not found or available

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "user group not found: 28c1251b-2f7c-4c58-95a1-fc4a1ead877e"
}