Users Management

Local Users Endpoints

Endpoints for viewing user(s), creating a user, updating a user, enabling or disabling a user.

• Display users : GET /api2/users admin
• Display user : GET /api2/users/{id} admin
• Create user : POST /api2/users admin
  • usage: the email, name, username, role and password fields are mandatory and should be passed in the request payload.
• Update user : PUT /api2/users/{id} admin
  • usage: the email, name, username, role and password fields are mandatory and should be passed in the request payload.
• Delete user : DELETE /api2/users/{id} admin
  • usage: the request body has to be empty

Json Structure

]
    {
        "id": 1,
        "name": "admin",
        "username": "admin",
        "email": "admin@profitap.com",
        "sshKey": "",
        "role": "admin",
        "enabled": true,
        "creation_time": 1542373932,
        "modification_time": 1542373932,
        "last_access": 0
    },
    {
        "id": 3,
        "name": "guest",
        "username": "guest",
        "email": "guest@profitap.com",
        "sshKey": null,
        "role": "viewer",
        "enabled": true,
        "creation_time": 1542373932,
        "modification_time": 1542373932,
        "last_access": 0
    }
]

Per-user Configuration

Each authenticated user (local or remote) has an associated opaque configuration blob, intended for client-owned settings (UI theme, layout, table column choices, etc.). The daemon stores the request body verbatim and returns it on demand — it does not parse or validate the payload.

For local users the blob lives on the user row and is removed when the user is deleted. For remote users (TACACS / RADIUS / LDAP / supervisor) the blob is keyed by (source, server_id, username) and is removed when the auth server is deleted, or after a configurable retention period of inactivity.

• Get current user's config : GET /api2/users/config viewer
• Set current user's config : PUT /api2/users/config viewer
• Get remote-user config retention : GET /api2/users/config/retention_time admin
• Set remote-user config retention : PUT /api2/users/config/retention_time admin

Get user config

GET /api2/users/config

Retrieves the configuration blob for the user identified by the request's authorization token. The response body is the raw stored payload (last value passed to PUT /api2/users/config), returned with Content-Type: application/json regardless of what the client originally PUT. The body is empty when no config has been set.

Required Role: viewer

Request headers

Authorization: <your-token>

Error responses

If the caller is a remote user and the auth server identified by the token's (source, hostname, port) has since been deleted:

{
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "The auth server for this token no longer exists."
}

Set user config

PUT /api2/users/config

Stores the request body verbatim as the calling user's configuration blob. Overwrites any existing value. The daemon does not parse or validate the payload.

Required Role: viewer

Request headers

Authorization: <your-token>
Content-Type: application/json

Request body

Any text payload. Typically a JSON document, but no schema is enforced.

Response json structure

{
    "statusCode": 200,
    "message": "Successfully updated user config."
}

Error responses

If the caller is a local user but no row with that username exists (e.g. the user was deleted between obtaining the token and the request):

{
    "statusCode": 404,
    "error": "Not Found",
    "message": "Local user not found."
}

If the caller is a remote user and the auth server has since been deleted:

{
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "The auth server for this token no longer exists."
}

Get user config retention

GET /api2/users/config/retention_time

Retrieves the current retention period (in days) for remote-user configuration entries. Remote users do not have a delete event from the daemon's perspective, so their cached configs are aged out after this many days of inactivity. Local users are unaffected.

Required Role: admin

Request headers

Authorization: <your-token>

Response json structure

{
    "retention_days": 30
}

Set user config retention

PUT /api2/users/config/retention_time

Configures the retention period (in days) for remote-user configuration entries. The setting is persisted and survives restarts.

Required Role: admin

Request headers

Authorization: <your-token>
Content-Type: application/json

Request json structure

{
    "retention_days": 30
}

Valid range: 1 to 365 days

Response json structure

{
    "statusCode": 200,
    "message": "Successfully updated the user config retention."
}

Error responses

If retention_days is missing, has the wrong type, or is outside 1..365, a standard validation error is returned. Example for an out-of-range value:

{
    "status_code": 400,
    "error": "Bad Request",
    "message": "The validation has failed.",
    "response": "The validation has failed on retention_days: Retention must be between 1 and 365 days",
    "validation": {
        "errors": [
            {
                "path": "/",
                "key": "retention_days",
                "message": "Retention must be between 1 and 365 days",
                "constraint": "user_config_retention_days_constraint"
            }
        ]
    }
}

For a missing field the entry under validation.errors[] is:

{
    "path": "/",
    "key": "retention_days",
    "message": "The retention_days field is required.",
    "constraint": "missing_field"
}

Back to X2-SERIES API Home