Users

Use these endpoints to manage local user accounts on the device through the HTTP API.

This guide covers how to:

• list users
• create a user
• update a username, role, lock state, or SNMPv3 settings
• change a user's password
• create or revoke a personal access token
• delete a user

SSH public key management is documented separately in Uploading SSH Keys to User.

Authentication

Use the same authentication methods supported by other secured endpoints:

• a session cookie returned by POST /api/login
• a bearer token in Authorization: Bearer <token>

Missing or invalid credentials return 401 Unauthorized. Accounts without the required role permission receive 403 Forbidden.

Permissions

Endpoint	Required access
GET /api/users	User list view permission
POST /api/users	User modification permission
PUT /api/users/userId	User modification permission
PUT /api/users/userId/password	User modification permission
DELETE /api/users/userId	User modification permission
POST /api/users/userId/token	User modification permission, or the authenticated user must match userId
DELETE /api/users/userId/token	User modification permission, or the authenticated user must match userId

Only the primary administrator role can lock or unlock another user through userIsLocked. The built-in primary admin account cannot be locked, deleted, or reassigned to a different role.

User Object

Typical responses from the user endpoints include fields such as:

Field	Type	Notes
id	string	User identifier used in /api/users/userId
username	string	Login name
roleId	integer	Assigned role
enabled	boolean	Read-only account status
created	integer	Unix timestamp
lastLogin	integer	Unix timestamp
userIsLocked	boolean	Current lock state, when included for the caller
accessToken	string	Empty or a short prefix of the existing token. The full token is only returned when you create it.
sshKeys	array	SSH key metadata, when available to the caller
snmpv3Access	boolean	Enables SNMPv3 settings for the user
snmpv3Security	string	authPriv, authNoPriv, or noAuthNoPriv
snmpv3User_id	string	SNMPv3 user ID
snmpv3AuthProtocol	string	SHA or MD5
snmpv3PrivProtocol	string	AES or DES
snmpv3AuthPass	string	Masked in normal responses
snmpv3PrivPass	string	Masked in normal responses

Responses may include additional read-only metadata depending on how the user account was created and how the device is configured.

Endpoints

GET /api/users

Returns the current list of local users.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  https://<host>/api/users

Response (200 OK):

JSON

[
  {
    "id": "1",
    "username": "admin",
    "roleId": 1,
    "enabled": true,
    "created": 1705000000,
    "lastLogin": 1706000000,
    "userIsLocked": false,
    "accessToken": "",
    "sshKeys": []
  },
  {
    "id": "7",
    "username": "ops-user",
    "roleId": 2,
    "enabled": true,
    "created": 1706100000,
    "lastLogin": 1706200000,
    "userIsLocked": false,
    "accessToken": "abcd",
    "sshKeys": []
  }
]

POST /api/users

Creates a new local user.

Headers: Content-Type: application/json

Body fields:

Field	Type	Required	Notes
username	string	yes	Must be unique, must not be root, and must be 100 characters or fewer
roleId	integer	yes	Must match an existing role
password	string	yes	Must meet the device password policy

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"ops-user","roleId":2,"password":"ExamplePassword123!"}' \
  https://<host>/api/users

Response (200 OK):

JSON

{
  "id": "7",
  "username": "ops-user",
  "roleId": 2,
  "enabled": true,
  "created": 1706100000,
  "lastLogin": 0,
  "userIsLocked": false,
  "accessToken": "",
  "sshKeys": []
}

PUT /api/users/userId

Updates one or more editable user fields. Omit any fields you do not want to change.

Headers: Content-Type: application/json

Editable fields:

Field	Type	Notes
username	string	Must be unique, must not be root, and must be 100 characters or fewer
roleId	integer	Must match an existing role
userIsLocked	boolean	true locks the user, false clears the lock
snmpv3Access	boolean	Enables or disables SNMPv3 for this user
snmpv3AuthPass	string	8 to 255 characters
snmpv3AuthProtocol	string	SHA or MD5
snmpv3PrivPass	string	8 to 255 characters
snmpv3PrivProtocol	string	AES or DES
snmpv3Security	string	authPriv, authNoPriv, or noAuthNoPriv
snmpv3User_id	string	Up to 255 characters

Use PUT /api/users/userId/password to change a password. The main update endpoint does not accept a password field.

Locking note: userIsLocked uses the same timed lockout mechanism as failed-sign-in protection. It is suitable for temporary lock and unlock workflows, not as a permanent account disable switch.

Example: rename a user and change the role

Bash

curl -k --cookie "SPID=TOKEN" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"username":"ops-team","roleId":3}' \
  https://<host>/api/users/7

Example: lock or unlock a user

Bash

curl -k --cookie "SPID=TOKEN" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"userIsLocked":true}' \
  https://<host>/api/users/7

Bash

curl -k --cookie "SPID=TOKEN" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"userIsLocked":false}' \
  https://<host>/api/users/7

Example: update SNMPv3 settings

Bash

curl -k --cookie "SPID=TOKEN" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"snmpv3Access":true,"snmpv3Security":"authPriv","snmpv3User_id":"ops-snmp","snmpv3AuthProtocol":"SHA","snmpv3AuthPass":"ExampleAuth123!","snmpv3PrivProtocol":"AES","snmpv3PrivPass":"ExamplePriv123!"}' \
  https://<host>/api/users/7

Response (200 OK):

JSON

{
  "id": "7",
  "username": "ops-team",
  "roleId": 3,
  "enabled": true,
  "created": 1706100000,
  "lastLogin": 1706200000,
  "userIsLocked": false,
  "accessToken": "",
  "sshKeys": [],
  "snmpv3Access": true,
  "snmpv3Security": "authPriv",
  "snmpv3User_id": "ops-snmp",
  "snmpv3AuthProtocol": "SHA",
  "snmpv3PrivProtocol": "AES",
  "snmpv3AuthPass": "-----",
  "snmpv3PrivPass": "-----"
}

PUT /api/users/userId/password

Changes a user's password.

Headers: Content-Type: application/json

Body fields:

Field	Type	Required	Notes
currentPassword	string	yes	Current password for the target user
newPassword	string	yes	New password that meets the device password policy

This endpoint is for changing a known password. It does not provide a separate admin-only password reset flow that bypasses currentPassword.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"currentPassword":"OldPassword123!","newPassword":"NewPassword123!"}' \
  https://<host>/api/users/7/password

Response (200 OK):

The response body is empty on success.

POST /api/users/userId/token

Creates or replaces a personal access token for the user.

If the user already has a token, the previous token is replaced. Save the returned value when you create it. Later user-list responses only expose a short prefix, not the full token.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  -X POST \
  https://<host>/api/users/7/token

Response (200 OK):

JSON

{
  "accessToken": "abc123exampletoken"
}

You can then use that token in later requests:

Bash

curl -k \
  -H "Authorization: Bearer abc123exampletoken" \
  https://<host>/api/users

DELETE /api/users/userId/token

Revokes the user's personal access token.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  -X DELETE \
  https://<host>/api/users/7/token

Response (200 OK):

JSON

{
  "accessToken": ""
}

DELETE /api/users/userId

Deletes a local user account.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  -X DELETE \
  https://<host>/api/users/7

Response (200 OK):

The response body is empty on success.

Related Endpoint

GET /api/user

Returns the currently signed-in user's own record, including role details.

For best results, call this endpoint with a session cookie from POST /api/login.

Example:

Bash

curl -k --cookie "SPID=TOKEN" \
  https://<host>/api/user

Error Codes

Status	Meaning
400 Bad Request	Reserved or unsupported input, such as an invalid built-in username
401 Unauthorized	Authentication failed or is missing
403 Forbidden	The authenticated account does not have permission for the request
404 Not Found	The endpoint or path is not supported
422 Unprocessable Entity	Invalid request body, duplicate username, invalid role, wrong current password, or unsupported field value
500 Internal Server Error	Unexpected failure applying the change

Notes

• Passwords and SNMPv3 secrets are not returned in clear text in normal user responses.
• userIsLocked is intended for temporary lockouts and manual unlocks, not long-term account disablement.
• The device protects the built-in primary admin account from deletion, role reassignment, and API lockout.