Using the User API

Overview

The User API is a simple way to add, remove, and edit user and usergroup accounts via HTTP or the command line. The API only accepts requests from hosts that are part of the authorized IPs whitelist.

Getting Started

Authentication

Determine the IP address from the list of IP addresses that can access the API. A whitelist of IPs is used for authentication. The whitelist is defined in $homeDir/files/auth_ips.cfg (one host IP per line).

The response for unauthenticated request is: {“msg”:”Request cannot be authenticated.”,”err”:”oauthFailure”}

Accessing the User API via HTTP

To access the API via HTTP a POST or GET request must be made to this base URI: “http://[SCRUTINIZER SERVER]/fcgi/scrut_fcgi.fcgi” passing the following mandatory fields:

  • rm=user_api
  • action=
  • json={}

rm=user_api is always the same every time we want to access the user API. action tells the API what we want to do. json will contain a JSON object with the details of the action that we want the User API to perform.

Examples

JavaScript

This example illustrates how to make an AJAX request to the User API using Javascript & jQuery

var  url  =  "http://[SCRUTINIZER SERVER]/fcgi/scrut_fcgi.fcgi";
var  action_details  =   {
    "users": [{
            "name": "MyAdmin",
                        "pass": "MyPass",
                        "membership": [1]
    },          {
            "name": "MyGuest",
                        "pass": "OtherPass",
                        "membership": [2]
    }    ]
};
$.ajax({
    type:   "POST",
        url:  url,
        data:  {
            rm :   "user_api",
                    action :   "createUser",
                    json :  JSON.stringify( action_details ),

    },
        success:   function ( response )  {
            if  ( response.err )  {
                    alert(response.msg);
            }
            else  {
                    console.log(response);
            }
            return;
    }
});

Python

This example illustrates how to make a request to the User API using Python

import urllib
import urllib2
import json
url = 'http://[SCRUTINIZER SERVER]/fcgi/scrut_fcgi.fcgi'
user_details = {
     'users'  :  [
         {
             'name' : 'MyAdmin',
             'pass' : 'MyPass',
             'membership' : [1]
         },
         {
             'name' : 'MyGuest',
             'pass' : 'OtherPass',
             'membership' : [2]
         }
     ]
 }
data = {
     'rm' : 'user_api',
     'action' : 'createUser',
     'json' : json.dumps( user_details )
 }
data = urllib.urlencode( data )
req = urllib2.Request( url, data )
response = urllib2.urlopen( req )
user_data = response.read()
user_obj = json.loads( user_data )

Reference Guide

rm=user_api

This URL field is required when making an HTTP request. This field is always equal to user_api.

action

Indicates what action we want the User API to perform with the JSON we provide. Below is a list of available actions.

createUser

Allows the creation of user accounts within Scrutinizer. They can be added to user groups at the same time.

JSON Object Expected

{
    "users": [
       {
            "name": "MyAdmin",
            "pass": "MyPass",
            "membership": [1]
       },
       {
            "name": "MyGuest",
            "pass": "OtherPass",
            "membership": [2]
       }
]}
  • users: An array of all users to be created, so multiple users can be created at once. If only one user is needed, this will be an array of one.

  • name: The name of the user to be created.

  • 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.

    JSON Object Returned

{
    "data": [
       {
            "id": 3,
            "name": "MyAdmin"
       },
       {
            "id": 4,
            "name": "MyGuest"
       }
]}
  • 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).

delUser

Allows the deletion of user accounts within Scrutinizer.

JSON Object Expected

{"delUsers":[
    2,
    "GuestUser",
    7
]}
  • delUsers must contain an array of user IDs or usernames of accounts to be deleted.

    JSON Object Returned

{"data":[
    "Deleting user 2",
    "Deleting user GuestUser",
    "Failed to delete 7 (No such account exists)"
]}
  • data: An array of responses for each user account that Scrutinizer attempted to delete.

createUsergroup

Allows the creation of usergroups within Scrutinizer. Members can be added at the same time.

JSON Object Expected

     {"usergroups":[
       {
           "name":"GroupA",
           "template_usergroup":1,
           "users":[1,2]
       },
       {
           "name":"GroupB",
           "template_usergroup":2,
           "users":["MyUser","MyUser2"]
       }
]}
  • name: The name of the usergroup to be created.

  • 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 usergroup.

    JSON Object Returned

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

delUsergroup

Allows the deletion of usergroups within Scrutinizer.

JSON Object Expected

{"delUsergroups":
   [
       3,
       "My Usergroup"
   ]
}
  • delUsergroups: Must contain an array of usergroup IDs or usergroup names to be deleted.

    JSON Object Returned

{"data":
   [
       "Usergroup 3 was deleted",
       "Failed to delete My Usergroup (No such group exists)"
   ]
}
  • data: An array of responses for each usergroup that Scrutinizer attempted to delete.

prefs

Changes user preferences for individual users

JSON Object Expected

{"user_id":5,
     "prefs":[
    {
        "pref":"statusTopn",
        "setting":10
    },
    {
        "pref":"language",
        "setting":"english"
    }
    ]}
  • user_id: Required for the user with preferences to change

  • prefs contains an array of preferences and new settings

    JSON Object Returned

{"data":
   "updated":[
       "statusTopn updated to 10 for user_id 5",
       "language updated to english for user_id 5"
   ],
   "errors":[
       "Failed to update user_id 5's preference favoriteIceCream: No such preference exists"
   ]
}
  • 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

changeUsergroupNames

Changes user preferences for individual users

JSON Object Expected

{"changeUsergroupNames":
   [
       {
           "id":3,
           "newname":"My Best Group"
       },
       {
           "oldname":"Sad Group",
           "newname":"Happy Group"
       },
   ]
}
  • changeUserGroupNames: An array of changes to be made to usergroups

  • id: The usergroups_id of a group the user desires to change

  • oldname: An alternative to the “id” parameter, and contains the current usergroup name

  • newname: The name this usergroup will be changed to have

    JSON Object Returned

{"data":
   "updated":[
       "Usergroup 3 renamed to My Best Group"
   ],
   "errors":[
       "Failed to rename Sad Group to Happy Group: Another usergroup already exists with this name."
   ]
}
  • data: An array of responses for each name change attempted
  • updated: Messages for any name successfully changed
  • errors: Any errors encountered while changing names

changeUsername

Changes usernames

JSON Object Expected

{"changeUsername":
   {
      "<user_id|oldname>":"<N|"myUser">,
      "newname":"OpSCT"
   }
}
  • 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 which is intended to change

    JSON Object Returned

{"data":
   {
       "message": "User myUser successfully renamed to OpSCT"
   }
}
  • message will contain either a statement of success or an error explaining why the name change failed

membership

Changes usergroup membership

JSON Object Expected

{"membership":
   {
      "add":[
           {
               "user_id":"N",
               "user_name":"USER1",
               "usergroup_id":"X",
               "usergroup_name":"USERGROUP1"
           },
           {
               "user_id":"M",
               "user_name":"USER2",
               "usergroup_id":"Y",
               "usergroup_name":"USERGROUP2"
           }
      ],
      "remove":[
           {
               "user_id":"L",
               "user_name":"USER3",
               "usergroup_id":"Z",
               "usergroup_name":"USERGROUP3"
           }
      ]
   }
}
  • membership contains two arrays, “add” and “remove,” which have information on each membership change

  • user_id is the ID from plixer.users the users wishes to add or remove

  • user_name is an alternative to user_id, and can be the plain text name of the user

  • usergroup_id is the ID from plixer.usergroups that the user will be added to or removed from

  • usergroup_name is an alternative to usergroup_id, and can be the plain text name of the usergroup

    JSON Object Returned

{"data":
   "added":[
       "User N added to usergroup X",
       "User M added to usergroup Y",
   ],
   "removed":[
       "User L removed from usergroup Z"
   ]
}
  • added will contain an array of either statements of success or errors explaining why the membership change failed
  • removed will contain an array of either statements of success or errors explaining why the membership change failed

permissions

Changes usergroup permissions

JSON Object Expected

{"permissions":
   {
      "add":[
           {
               "usergroup_id":X,
               "usergroup_name","USERGROUP1",
               "type":<usergroups_permissions.fk>,
               "secCode":?
           }
      ],
      "remove":[
           {
               "usergroup_id":X,
               "usergroup_name","USERGROUP3",
               "type":<usergroups_permissions.fk>,
               "secCode":?
           }
      ]
   }
}
  • permissions will contain two arrays, “add” and “remove,” for each permission to be changed

  • usergroup_id is the ID from plixer.usergroups that the user will be added to or removed from

  • usergroup_name is an alternative to usergroup_id, and can be the plain text name of the usergroup

  • type can be found in plixer.usergroups_permissions in the ‘fk’ field. It differentiates the types of permissions (e.g. “int,” “dev,” etc.)

  • 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.)

    JSON Object Returned

{"data":
   "updated":[
       "Added permission int-1 to usergroup USERGROUP1",
   ],
   "errors":[
       "Failed to remove permission dev-0A010107 from usergroup USERGROUP3: Permission not currently assigned to this usergroup"
   ]
}
  • updated will contain an array of either statements of success or errors explaining why the permission change failed
  • errors will contain an array of either statements of success or errors explaining why the permission change failed