Skip to content

Authentication and user management REST interface

Get the authentication status

Retrieve whether authentication is turned on.

Definition

1
GET /api/users/auth_status

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/auth_status" \
     -u admin:admin

Example response

1
true

Returns

Boolean value describes the status of the authentication.

Get username of the current user

Retrieve the username of the current user.

Definition

1
GET /api/users/username

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/username" \
     -u admin:admin

Example response

1
"admin"

Returns

String representation of the username.

Get WebSocket pass of the current user

Retrieve the pass used to authenticate the current user via WebSocket.

Definition

1
GET /api/users/pass

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/pass" \
     -u admin:admin

Example response

1
"7f9449854c2fef8d14de44f84a753c49"

Returns

String representation of the WebSocket pass.

Get whether current user is admin

Retrieve whether the current user is admin (only when authentication is enabled).

Definition

1
GET /api/users/is_admin

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/is_admin" \
     -u admin:admin

Example response

1
true

Returns

Return true if authentication is enabled and the current user is admin. Otherwise return false.

Get role of the specified user

Retrieve the role of the specified user. This can be one of the following: guest, user, admin.

Definition

1
GET /api/users/role/USERNAME

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/role/admin" \
     -u admin:admin

Example response

1
admin

Arguments

Argument Description
username Required. The string value of the username.

Returns

If successful, the response is the role of the user.

Limitations

Request is restricted to admin and the specified user. If a non-admin user sends this request with another username then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Get rights of the specified user

Retrieve a list of rights. These can be read, write or execute.

Definition

1
GET /api/users/rights/USERNAME

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/rights/admin" \
     -u admin:admin

Example response

1
[]

Arguments

Argument Description
username Required. The string value of the username.

Returns

If successful, the response is a list of rights belongs to the user specified in the request.

Limitations

Request is restricted to admin and the specified user. If a non-admin user sends this request with another username then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Set new password for the current user

Change the password of the current user.

Definition

1
POST /api/users/change_password

Data

1
2
3
{
  "password": "PASSWORD"
}

Example request

1
2
3
4
curl -X POST "http://127.0.0.1:8080/api/users/change_password" \
     -H "Content-Type: application/json" \
     -d "{\"password\":\"newPassword12\"}" \
     -u admin:admin

Example response

1
true

Arguments

Argument Description
password Required. The string value of the new password.

Returns

If successful, the HTTP response is 200 OK. The new password is stored. Otherwise, HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Limitations

Password can consist of letters and numbers.

Set role of the specified user

Set the role of the specified user. Request is restricted to admin.

Definition

1
POST /api/users/change_role

Data

1
2
3
4
{
  "username" : "USERNAME",
  "role" : "ROLE"
}

Example request

1
2
3
4
5
curl -X POST "http://127.0.0.1:8080/api/users/change_role" \
     -H "Content-Type: application/json" \
     -d "{\"username\":\"admin\",
          \"role\":\"admin\"}" \
     -u admin:admin

Example response

1
true

Arguments

Argument Description
username Required. The string value of the username.
role Required. The string value of the role.

Returns

If successful, the HTTP response is 200 OK. Otherwise, HTTP 400 is sent with an error object:

1
{"errror" : "ERROR_REASON_STR"}

Limitations

Request is restricted to admin. If other user sends this request then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Set rights of the specified user

Set the rights of the specified user. Request is restricted to admin.

Definition

1
POST /api/users/change_rights

Data

1
2
3
4
{
  "username" : "USERNAME",
  "rights" : ["RIGHT"]
}

Example request

1
2
3
4
5
curl -X POST "http://127.0.0.1:8080/api/users/change_rights" \
     -H "Content-Type: application/json" \
     -d "{\"username\":\"admin\",
          \"rights\":[]}" \
     -u admin:admin

Example response

1
true

Arguments

Argument Description
username Required. The string value of the username.
rights Required. A list of rights as string values.

Returns

If successful, the HTTP response is 200 OK. Otherwise, HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Limitations

Request is restricted to admin. If another user sends this request then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Get the list of registered users

Retrieve a list of registered users.

Definition

1
GET /api/users/list_users

Example request

1
2
curl -X GET "http://127.0.0.1:8080/api/users/list_users" \
     -u admin:admin

Example response

1
2
3
{
  ["admin","user2","user"]
}

Returns

The array of the registered users's username. Usernames are represented as strings.

Limitations

Request is restricted to admin. If other user sends this request then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Add new user

Add a new user with the specified credentials.

Definition

1
POST /api/users/add_user

Data

1
2
3
4
{
  "username": "USERNAME"
  "password": "PASSWORD"
}

Example request

1
2
3
4
5
curl -X POST "http://127.0.0.1:8080/api/users/add_user" \
     -H "Content-Type: application/json" \
     -d "{\"password\":\"newPassword12\",
          \"username\":\"newUser\"}" \
     -u admin:admin

Example response

1
true

Arguments

Argument Description
username Required. The string value of the username.
password Required. The string value of the password.

Returns

If successful, the HTTP response is 200 OK. The new user is stored with the specified credentials. Otherwise, HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Limitations

Username and password can consist of letters and numbers.

Request is restricted to admin. If other user sends this request then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Delete user

Delete the specified user.

Definition

1
DELETE /api/users/delete_user/USERNAME

or

1
DELETE /api/users/delete_user/USERNAME?with_pages=true

Data

none

Example request

1
2
curl -X DELETE "http://127.0.0.1:8080/api/users/delete_user/newUser?with_pages=true" \
     -u admin:admin

Example response

1
true

Arguments

Argument Description
username Required. The string value of the username.
with_pages Optional. If defined and the value is true then the front pages owned by the user will be deleted. Otherwise, the new owner will be the admin user.

Returns

If successful, the HTTP response is 200 OK. The user is deleted. Otherwise, HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}

Limitations

Username can consist of letters and numbers.

Request is restricted to admin. If other user sends this request then HTTP 400 is sent with an error object:

1
{"error" : "ERROR_REASON_STR"}