
= Users

Since users are not currently stored in the database, the REST interface for them is not as full-fledged as that of nodes, etc.

IMPORTANT: You cannot use hibernate criteria for filtering.
You may need to touch the `$\{OPENNMS_HOME}/etc/users.xml` file on the filesystem for any addition or modification actions to take effect (see link:http://jira.opennms.org/browse/NMS-6469[NMS-6469] for details).

== GETs (reading data)

[caption=]
.Users API GET functions
[options="autowidth"]
|===
| Parameter | Description

| /users
| Get a list of users.

| /users/\{username}
| Get a specific user, by username.
|===

== POST (adding data)

[caption=]
.Users API POST function
[cols="1,3"]
|===
| Parameter | Description

| /users
| Add a user.
If supplying a password it is assumed to be hashed or encrypted already. +
To indicate that the supplied password uses the salted encryption algorithm rather than the older MD5-based algorithm, you need to pass an element named `passwordSalt` with text `true` after the password element (or key/value pairs if using JSON). +
Note that you may add the query parameter `hashPassword=true` to tell OpenNMS you are passing an unencrypted password; it will hash and salt the password when it is saved.
|===

== PUTs (modifying data)

[caption=]
.Users API PUT functions
[cols="1,3"]
|===
| Parameter | Description

| /users/\{username}
| Update an existing user's `full-name`, `user-comments`, `password`, `passwordSalt`, and `duty-schedule` values. +
Note that, if you are setting the password, you may also add the query parameter `hashPassword=true` to tell OpenNMS you are passing an unencrypted password so it will hash and salt the password when it is saved.

| /users/\{username}/roles/\{rolename}
| Add a security role to the user.
|===

== DELETEs (removing data)

[caption=]
.Users API DELETE functions
[options="autowidth"]
|===
| Resource  | Description

| /users/\{username}
| Delete a user.

| /users/\{username}/roles/\{rolename}
| Remove a security role from the user.
|===
