User API

Overview

The user API functionality allows creating user accounts within Plixer Scrutinizer and adding them to user groups at the same time.

Prerequisites

When using the API, pass the following mandatory fields:

authToken
The authentication token from Scrutinizer that allows access to API.
rm
The runmode for accessing the API. It is specific to each section of the product. user_api will be used for each of the following examples.
action
The list of available actions will change with each request. Below is a list of available actions within the user_api run mode:

Creating users

The createUser action allows creating users within the API. It calls for an additional field:

json
An array of users each contains the name, password and group template that user will be a member of.

JSON object expected:

{
 "users":[
     {
         "name": "MyAdmin",
         "pass":"secretAdminPass",
         "membership":[2]
     },
     {
         "name": "MyGuest",
         "pass":"myGuestPass",
         "membership":[2]
     }
 ]
}
Field Description
users An array of all users to be created. Multiple users can be created at once. If only one user is needed, this will be an array of one.
name The name for the new user account.
pass The password for the new user account.
membership An array of usergroup_ids from the plixer.usergroups table. The user will be added to these groups when the account is created. You can add your own usergroups. By default, there are two groups installed. Group 1 is the Administrators group. Group 2 is reservered for Guests.

JSON object returned:

{
 "data": [
     {
         "id": 3,
         "name": "MyAdmin"
     },
     {
         "id": 4,
         "name": "MyGuest"
     }
 ]
}
Field Description
data An array of responses for each user account that Scrutinizer attempted to create.
id The new user_id of the user account that was created.
name The name of the account created (by design this is identical to the name passed in).

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=createUser' \
 --form 'json=
 {
     "users":[
         {
             "name": "MyAdmin",
             "pass": "MyPass",
             "membership": [ 1 ]
         },
         {
             "name": "MyGuest",
             "pass": "OtherPass",
             "membership": [ 2 ]
         }
     ]
 }'

Note

If Plixer Scrutinizer is using a self-signed certificate, add --insecure to the header options to tell curl to ignore it.

Deleting users

The delUser action allows the deletion of user accounts within Plixer Scrutinizer by ID or name. There is an additional field used with the action:

json
An array of users where each contains the name, password and group template that user will be a member of.

JSON object expected:

{
 "delUsers":[
         11,
         "MyGuest",
         207
 ]
}
Field Description
delUsers An array of all users to be deleted. You can delete multiple users at once. If only one user is needed, this will be an array of one.
id/name The user_id of the user to be deleted. Alternatively, the name of the user can be used also.

JSON object returned:

{
 "data":[
     "Deleting user id 11 (1 matched)",
     "Deleting user named 'MyGuest' (1 matched)"
     "Deleting user id 207 (0 matched)",
 ]
}
Field Description
data An array of responses for each user account that Plixer Scrutinizer attempted to delete. The example includes a failure message when a user did not exist.

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=delUsers' \
 --form 'json=
 {
     "delUsers":[
         11,
         "MyGuest",
         207
     ]
 }'

Creating Usergroups

You can use the createUsergroup action to create user groups and add members at the same time. It requires an additional field:

json
An array of usergroups. Each entry contains the name of the usergroup, the id of the usergroup to use as a template, and the id or name of the users to be added to the group.

JSON object expected:

{
 "usergroups":[
     {
         "name":"GroupA",
         "template_usergroup":1,
         "users":[1,2]
     },
     {
         "name":"GroupB",
         "template_usergroup":2,
         "users":["MyUser","MyUser2"]
     }
 ]
}
Field Description
usergroups An array of responses for each usergroup that Scrutinizer attempted to create.
name The name to be applied to the usergroup
template_usergroup the id of the user group to use as a template for creating a new user group.
users An array of all users to be added, by user ID or username. If only one user is needed, this will be an array of one. An empty array will create an empty user group

JSON object returned:

{
 "data":[
     {
         "id":5,
         "name":"GroupA",
         "members":["1","2"]
     },
     {
         "name":"GroupB",
         "error":"A usergroup already exists with that name"
     }
 ]
}
Field Description
data An array of responses for each user group that Plixer Scrutinizer attempted to create.
id The new usergroups_id of the user group that was created.
name The name of the user group created (by design this is identical to the name passed in)
members An array of user IDs or user names for the members successfully added to the group
error Any errors encountered during the creation of a particular user group

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=createUsergroup' \
 --form 'json=
 {
     "usergroups":[
         {
             "name":"GroupA",
             "template_usergroup":1,
             "users":[1,2]
         },
         {
             "name":"GroupB",
             "template_usergroup":2,
             "users":["MyUser","MyUser2"]
         }
     ]
 }'

Deleting user groups

The delUsergroups action deletes user groups. It has an additional field:

json
An array of usergroups. Each entry contains the name or ID of the usergroup to be deleted.

JSON object expected:

{
 "delUsergroups": [
     3,
     "My Usergroup"
 ]
}
Field Description
delUsergroups An array of responses for each user group that Scrutinizer attempted to delete
id/name The usergroups_id or exact name of the user group to be deleted

JSON object returned:

{
 "data":[
     "Deleting usergroup named '3' (1 matched)",
     "Deleting usergroup id My Usergroup (0 matched)"
 ]
}
Field Description
data An array of responses for each usergroup that Plixer Scrutinizer attempted to delete.

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=delUsergroups' \
 --form 'json=
 {
     "delUsergroups": [
         3,
         "My Usergroup"
     ]
 }'

Modifing group membership

The membership action changes user group membership. When adding or removing a user, use either “user_id” or “user_name”, but not both as shown below. There is an additional field that can be used with the membership action in the user API:

json
Contains two arrays, “add” and “remove,” which have information on each membership change.

JSON object expected:

{
 "membership":
     {
     "add":[
         {
             "user_id": 13,
             "usergroup_id": 2
         },
         {
             "user_name":"USER2",
             "usergroup_name":"USERGROUP2"
         }
     ],
     "remove":[
         {
             "user_name":"USER3",
             "usergroup_id": 4
         }
     ]
 }
}
Field Description
membership Contains two arrays, “add” and “remove,” which have information on each membership change
user_id Required for the user with preferences to change
user_name An alternative to user_id. It can be the plain text name of the user.
usergroup_id The ID from plixer.usergroups that the user will be added to or removed from.
usergroup_name An alternative to usergroup_id. It can be the plain text name of the user group.

JSON object returned:

{
 "data":
     "added":[
         "User 13 added to usergroup 1",
         "User 14 added to usergroup 3",
     ],
     "removed":[
         "User 15 removed from usergroup 4"
     ]
}
Field Description
data An array of responses for membership updated
added Contains an array of either statements of success or statements of errors explaining why the membership change failed
removed Contains an array of either statements of success or statements of errors explaining why the membership change failed

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=membership' \
 --form 'json=
 {
     "membership": {
         "add": [
             {
                 "user_id": 3,
                 "usergroup_id": 17
             },
             {
                 "user_id": "USER2",
                 "usergroup_id": "GROUPB"
             }
         ],
         "remove": []
     }
 }'

Editing user preferences

The prefs action makes changes to the user preferences for individual accounts. It contains an array of preferences and new settings.There is an additional field used with the prefs action in the user API:

json
the user_id and array of prefs each contains the pref code and setting value to be modified.

JSON object expected:

{
 "user_id": 11,
 "prefs":[
     {
         "pref":"statusTopn",
         "setting":10
     },
     {
         "pref":"language",
         "setting":"english"
     }
 ]
}
Field Description
user_id Required for the user with preferences to change
prefs An array of user preferences and setting values
pref The Scrutinizer user preference to edit
setting The value that will be set for the user_id specified

JSON object returned:

{
 "data": {
     "updated": [
         "statusTopn updated to 10 for user_id 11",
         "language updated to english for user_id 11"
     ],
     "errors": []
 }
}
Field Description
data An array of responses for each preference change updated or attempted
updated Messages for any preference successfully changed
errors Any errors encountered while changing preferences

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=prefs' \
 --form 'json=
 {
     "user_id":11,
     "prefs":[
         {
             "pref":"statusTopn",
             "setting":10
         },
         {
             "pref":"language",
             "setting":"english"
         }
     ]
 }'

Changing permissions

The permission action makes changes to a user group’s permissions. Users inherit permissions from their user group. There is an additional field used with the permissions action in the user API:

json
An array of permissions each contains a usergroup identifier (name or ID), the security code and permission type to be modified.

JSON object expected:

{
 "permissions": {
     "add": [
         {
             "usergroup_name": "Dashboarders",
             "permission_type": "gadget",
             "seccode": "lLabelCPU"
         }
     ],
     "remove": [
         {
             "usergroup_name": "ReadOnlyReporters",
             "permission_type": "plixer",
             "seccode": "allGadgets"
         }
     ]
 }
}
Field Description
permissions Contains two arrays, “add” and “remove,” which have information on each permission change
add/remove Each contains an array of objects of permissions and user groups
usergroup_id The ID from plixer.usergroups that the user will be added to or removed from
usergroup_name An alternative to usergroup_id, and can be the plain text name of the user grou
permission_type differentiates the types of permissions. Options include:
  Permission Description
device A hex representation of the IP address of a device (e.g. ‘0A010107’)
interface Hyphenated, a hex representation of the IP address of a device followed by the interface index (e.g. ‘0A010107-1’)
group The group ID of a map/device group from plixer.groups
report The saved_id of a saved report from reporting.saved_reports
gadget The gadget_id of a dashboard gadget, from plixer.dash_gadgets (e.g. ‘welcomeGadget’)
thirdparty The id of a 3rd party link from plixer.third_party
bboard The bulletin board id from plixer.alm_bulletin_boards
plixer A static string of permission codes we use for different parts of the product (e.g. ‘adminTab’ or ‘viewUserIdentity’). There are over 30 of these on initial install and control a wide range of feature access.
seccode another field in plixer.usergroups_permissions and contains the permission. It will be different depending on the “type” (e.g. “1” for interface 1, “0A010107” for a device, etc.)
  seccode Description
3rdPartyIntegration Create, edit, and delete third-party integration links
ackBBEvent Ability to acknowledge events on Alarms tab bulletin boards
adminTab Access the Admin Tab
alarmSettings Configure alarm notifications
alarmsTab Access the Alarms tab
allBBoards View all Alarms bulletin boards
allDevices The status of all devices and each of their interfaces
allGadgets Every gadget created on the Dashboards tab, by any user
allGroups Access to all maps/device groups created in Scrutinizer
allInterfaces Report on interfaces for any device
allLogalotReports All Logalot Reports
allReportFolders Permission to all saved report folders
allReports Saved reports created by any user
allThirdparty All configured third-party links will be available
almDelete Permission to permanently delete alarms
ApplicationGroups Configure Application Groups
asnames Configure AS Names
auditing Access the Auditing report containing logs of Scrutinizer user actions
auth Manage external authentication tokens
Authentication Manage external authentication types
authLdapServers Manage LDAP server configuration used for Scrutinizer authentication
awsSettings AWS configuration
changeUserPasswords The ability to change the passwords of other users without needing their credentials
createDashTabs Create new Dashboards
createUsers The ability to create new local Scrutinizer user accounts
CrossCheck View and edit CrossCheck configuration, which determines device up/down status
crossCheckView Access to the CrossCheck methods table view in Status > Views
dashboardAdmin Manage all dashboards created by any user
DataHistory Configure settings that control how long Scrutinizer stores data of different granularities
deleteReport Ability to delete saved reports regardless of owner
deleteUsers The ability to delete local Scrutinizer user accounts
DeviceDetails Edit device interface details
EmailNotifications Configure the mailserver Scrutinizer will use to send reports and emails
faExclusions Configure Flow Analytics exclusions
fa_mgmt_link Configure Flow Analytics thresholds and settings
feedbackForm Access the link to send feedback to Plixer
FlowAnalyticsSettings Global Flow Analytics settings
helpTab Access the Help tab
HostNames Edit Host Name information
IPGroups Configure Scrutinizer IP Groups
language Create and edit language localization settings
licensing Configure Scrutinizer product licensing and features
LogalotPrefs Configure global alarms settings
MACAddresses Configure device MAC Address information
ManageCollectors Manage the devices collecting flow data for Scrutinizer
ManageExporters Manage the devices exporting flow data to Scrutinizer
mappingGroupConfiguration Create and edit Maps/Groups
mappingObjectConfiguration Create and edit Mapping Objects
mapsTab Access the Maps tab
myViewTab Access the Dashboards tab
NotificationManager Manage alarm notifications
PolicyManager Manage alarm policies
protocolExclusions Edit which protocols are discarded from flow reports
proxySettings Configure proxy server settings in Scrutinizer
radiusConf Manage RADIUS server configuration used for Scrutinizer authentication
ReportDesigner Design new custom report types
reportFilters Permission to update the filters used in Status Tab reports
reportFolders Manage saved report folders
reportSettings Reporting engine configuration options
runReport Ability to run flow reports
saveReport Ability to name and save flow reports
scheduledReports Create, edit, and delete scheduled email reports
sf_asa_acls Configure ASA ACL descriptions
SNMPCredentials Manage SNMP credentials used to poll device information
srCreate Schedule a saved report to be emailed on a regular basis
sso Add, Delete, and Edit Identity Provider configuration for Scrutinizer’s Single Sign-On Integration
statusTab Access the Status Tab
syslogNotifications Syslog server configuration
SystemPreferences Administrative access to global Scrutinizer preferences
tacacsConf Manage TACACS+ server configuration used for Scrutinizer authentication
tos Edit TOS Configuration
userAccounts Access to the Users view on the Admin Tab, listing ALL users instead of only the current one
usergroups Manage Scrutinizer usergroups
viewUserIdentity View identity and access information relevant to GDPR restrictions
viptelaSettings Viptela Settings
Vitals View the Scrutinizer server vitals reports
wkp Edit WKP Configuration

JSON object returned:

{
 "data": {
     "errors": [],
     "updated": [
         "Added gadget permission lLabelCPU to usergroup 26 ",
         "Removed plixer permission allGadgets from usergroup 27 "
     ]
 }
}
Field Description
data An array of responses for each permission change updated or attempted
updated Messages for any sucessful changes to permissions
errors An array of errors explaining why the permission change failed

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=permissions' \
 --form 'json=
 {
     "permissions": {
         "add": [
             {
                 "usergroup_id": 23,
                 "permission_type": "plixer",
                 "seccode":   "statusTab"
             }
         ],
         "remove": []
     }
 }'

Changing user names

The changeUsername action allows editing the name of a user account. It requires an additional field:

json
An array of user groups each containing the existing name of user, the new user name to be set. Alternatively, the user_id can be used instead of the oldname field.

JSON object expected:

{
 "changeUsername":
     {
         "user_id":"14",
         "newname":"OpSCT"
     }
}
Field Description
user_id The user ID of the account to be changed
oldname An alternative to user ID, and contains the current name of the user
newname Contains the name to which you wish to change this user

JSON object returned:

{
 "data":
     {
         "message": "User myUser successfully renamed to OpSCT"
     }
}
Field Description
data An array of responses for each preference change updated or attempted
message Contains either a statement of success or an error explaining why the name change failed

Example API call

curl --location --insecure --request POST '{{scrutinizer}}/fcgi/scrut_fcgi.fcgi' \
 --form 'authToken={{authToken}}' \
 --form 'rm=user_api' \
 --form 'action=changeUsername' \
 --form 'json=
 {
     "changeUsername":
         {
             "oldname":"myUser",
             "newname":"OpSCT"
         }
 }'