Users REST Interface

Data

A userdata data structure contains the following fields:

username The username (must be unique for the whole installation).

password The user’s password. Can’t be retrieved with GET.

enabled A true / false value. Disabled users aren’t removed but can’t login anymore.

email The email address of the user.

fullname A descriptive name of the user.

groups [ 'group1', 'group2', ... ] A list of the user groups that this user belongs to.

last_login UNIX timestamp of the most recent login (this is the time in seconds counted from Jan. 1st 1970). Can’t be set via POST and PUT.

last_failed_login UNIX timestamp of the most recent failed login. Can’t be set with POST and PUT.

For more information regarding user and user group management, see User Management and User Groups REST Interface.

Getting a list of users

Request

Method	GET
URL	/auth/users/
Arguments	–

Response

Return code	Arguments	Meaning
200	[ user1, user2, ... ]	list of usernames successfully returned
401	-	no login
403	-	not enough rights
500	-	internal server error

Example

The following request retrieves a list of all users. In this case, there is only one user: the user “admin”.

$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/auth/users {    "__name": "users",    "__path": "/api/af/2.0/auth/users/",    "__subnodes": [        "admin"    ],    "users": [        "admin"    ] }

Getting the data of a user

Request

Method	GET
URL	/auth/users/USERNAME
Arguments	–

Response

Return code	Arguments	Meaning
200	{ USERDATA }	user data successfully returned
401	-	no login
403	-	not enough rights
404	-	user not found
500	-	internal server error

Example

The following request retrieves the user data of the user "admin".

$ curl -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/auth/users/admin { "__name": "admin", "__path": "/api/af/2.0/auth/users/admin/", "__subnodes": [], "email": "", "enabled": true, "fullname": "Administrator", "groups": [ "master_admin" ], "last_failed_login": 0, "last_login": 1347291994, "username": "admin" }

Adding a user

Request

Method	POST
URL	/auth/users/
Arguments	{ USERDATA } The username is always required. If not otherwise specified, a new user is automatically enabled by default. To prevent this, you can set 'enabled': false.

You can’t set the fields last_login and last_failed_login.

Response

Return code	Arguments	Meaning
200		user successfully added
401	-	no login
403	-	not enough rights
409	-	malformed, conflicting, or missing data
500	-	internal server error

Changing user data

Request

Method	PUT
URL	/auth/users/USERNAME
Arguments	{ USERDATA } You can’t rename a user. Retrieve the user information, remove the user and add a new one with another name.

Response

Return code	Arguments	Meaning
200	-	user data successfully changed
401	-	no login
403	-	not enough rights
404	-	user not found
409	-	malformed, conflicting, or missing data
500	-	internal server error

You can't set the fields last_login and last_failed_login.

Example

The following request changes the full name of the user "admin" from "Administrator" to "John Doe".

$ curl -u admin:admin -H 'Content-Type: application/json' --data '{"fullname": "John Doe"}' http://127.0.0.1:8087/api/af/2.0/auth/users/admin {    "__name": "admin",    "__path": "/api/af/2.0/auth/users/admin/",    "__subnodes": [],    "email": "",    "enabled": true,    "fullname": "John Doe",    "groups": [        "master_admin"    ],    "last_failed_login": 0,    "last_login": 1347291994,    "username": "admin" }

Removing a user

Request

Method	DELETE
URL	/auth/users/USERNAME
Arguments	–

Response

Return code	Arguments	Meaning
200	-	user successfully removed
401	-	no login
403	-	not enough rights
404	-	user not found
409	-	you can't delete your own account
500	-	internal server error

Example

The following request tries to delete the use "admin". This isn't possible because the request is authenticated as the user "admin", and users can't remove themselves. vWAF returns an error message telling you why the action wasn't possible.

$ curl -X DELETE -u admin:admin -H 'Content-Type: application/json' http://127.0.0.1:8087/api/af/2.0/auth/users/admin You can't delete your own account