Users

Manage the local user accounts of the device

Users authenticated through RADIUS, TACACS+ or LDAP have no local record. Such a user can call these endpoints only with the admin role and always acts on other users’ records.

API

• Data:

  • USER object:

    {
        "id": 2,
        "username": "operator1",
        "name": "First_Operator",
        "email": "operator@example.com",
        "role": "operator",
        "active": true,
        "creation_time": 1790332850,
        "modification_time": 1790332854,
        "last_access": 1790332853,
        "custom_config": {}
    }

    • id - unsigned integer, assigned by the device (read-only)
    • username - string, lowercase, starts with a letter followed by letters, numbers or underscores, 1 to 32 characters
    • password - string, at least 8 characters with 1 number, 1 lowercase and 1 uppercase letter; accepted in requests, never returned
    • name - string or null, letters, numbers or underscores only, 1 to 255 characters
    • email - string or null, must be a valid e-mail address
    • role - viewer, operator or admin; defaults to viewer
    • active - true if the user may log in; defaults to false
    • creation_time, modification_time, last_access - epoch seconds (read-only)
    • custom_config - reserved for GUI settings, currently always an empty object

    A field that violates its constraint is rejected with 422 and a Validation errors: ... message that names the field (see Responses).

• Get all users
  • Path: /api/users
  • Method: GET
  • Minimum user role: admin
  • Response on success (200 OK): array of USER objects in data
• Get a user
  • Path: /api/users/{id}
  • Method: GET
  • Minimum user role: viewer for the own record, admin for any other
  • Response on success (200 OK): USER object in data
  • Response on failure: 400 if {id} is not a number, 404 if no such user, 401 Insufficient permission when a non-admin asks for another user
• Add a user
  • Path: /api/users
  • Method: POST
  • Minimum user role: admin
  • Request body: USER object without id; username and password are mandatory, name and email may be omitted or null
  • Response on success (200 OK): message Successfully added the user., the created USER in data
  • Response on failure: 409 The username already exists: <username>, 422 on a constraint violation
  • Notes: a user created without "active": true cannot log in until an admin enables the account.
• Modify a user
  • Path: /api/users/{id}
  • Method: PUT
  • Minimum user role: viewer for the own record, admin for any other
  • Request body: USER object; fields that are omitted keep their current value, so a partial body such as {"name": "New_Name"} is valid. Sending password sets a new password.
  • Response on success (200 OK): message Successfully updated the user., the updated USER in data
  • Response on failure: 404 if no such user, 409 if the new username is taken, 422 on a constraint violation, and 400 for the self-modification rules below
  • Notes:
    • No user, including an admin, can change their own role (The user cannot change their access level) or active flag (The user cannot disable itself).
    • A non-admin cannot change their own username (Non-admin user cannot change their own username).
    • Changing the own password invalidates the current token; log in again with the new password.
• Delete a user
  • Path: /api/users/{id}
  • Method: DELETE
  • Minimum user role: admin
  • Response on success (200 OK): message Successfully deleted the user., the deleted USER in data
  • Response on failure: 400 The user cannot delete itself, 404 if no such user

Back to Index