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:

Action	Description
createUser	Allows the creation of user accounts within Plixer Scrutinizer. You can add the accounts to user groups at the same time.
delUsers	Allows the deletion of user accounts within Plixer Scrutinizer by ID or name.
createUsergroup	Creates user groups. You can add members at the same time.
delUsergroups	Deletes user groups.
membership	Changes usergroup membership. When adding or removing a user, either “user_id” or “user_name” would be used but, not both as shown below.
prefs	Makes changes to the user preferences for individual accounts. It contains an array of preferences and new settings.
permissions	Makes changes to a user group’s permissions.
changeUsername	Changes the name of a user account.

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"
         }
 }'