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