Crypt Vault Storage Remote API

Copyright 2015, Bryan Nielsen <bnielsen1965@gmail.com>

Version 1.0

Table of Contents

Table of Contents

Introduction

API Messages

Session Cookies

Session GUID

Methods

authenticate

Parameters

Example Request

Example Response

logout

Parameters

Example Request

Example Response

changePassword

Parameters

Example Request

Example Response

makePhrase

Parameters

Example Request

Example Response

makeKey

Parameters

Example Request

Example Response

toggleEnableKey

Parameters

Example Request

Example Response

toggleRemoteKey

Parameters

Example Request

Example Response

getKeyList

Parameters

Example Request

Example Response

getKeyNameList

Parameters

Example Request

Example Response

deleteKey

Parameters

Example Request

Example Response

getKeyRingList

Parameters

Example Request

Example Response

saveUserKeyRing

Parameters

Example Request

Example Response

saveUserKeyRingToUser

Parameters

Example Request

Example Response

addToKeyRing

Parameters

Example Request

Example Response

deleteKeyRingKey

Parameters

Example Request

Example Response

reloadKeyRing

Parameters

Example Request

Example Response

getRecordList

Parameters

Example Request

Example Response

saveRecord

Parameters

Example Request

Example Response

readRecord

Parameters

Example Request

Example Response

deleteRecord

Parameters

Example Request

Example Response

getUserList

Parameters

Example Request

Example Response

saveUser

Parameters

Example Request

Example Response

deleteUser

Parameters

Example Request

Example Response

getLogList

Parameters

Example Request

Example Response

exportLogList

Parameters

Example Request

Example Response

deleteLogList

Parameters

Example Request

Example Response

Appendix

User Flags

User Flag Values

Key Flags

Key Flag Values

Introduction

The remote API provides all the methods needed to operate the Crypt Vault. This makes it possible to integrate the Crypt Vault Storage into any application without the need to use the PHP libraries. As an example, the administration page uses the remote API to process all administration requests, which means any action that is performed on the administration page is also available to your applications through the remote API.

API Messages

The remote API uses JSON messages in the body of HTTP POST requests. Each request must contain at least the API method to execute. Each method may require additional parameters. The following example is a raw HTTP POST to a Crypt Vault Storage installation with a request to save a new record...

POST /cryptvaultstorage/cvs/api.php HTTP/1.1

Host: getwebscripts.com

Content-Type: application/json

Cache-Control: no-cache

{

    "method": "saveRecord",

    "keyName": "New Subscriptions",

    "description": "New Subscription From: Bob Toad",

    "data": "Client: Bob Toad\nEmail: bobt@bobtoad.org"

}

Assuming the saveRecord request in the previous example is successful the response may look something like the following…

HTTP/1.1 200 OK

Cache-Control: no-cache, must-revalidate
Connection: close
Content-Length: 72

Set-Cookie: cvssession=vke8v7r46ea8d6aakr817lr695; path=/
Content-Type: application/json
Date: Wed, 07 Oct 2015 02:45:46 GMT
Expires: Mon, 26 Jul 1997 05:00:00 GMT
Pragma: no-cache
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.3.3

{

  "id": "fea109f5-ab87-4bf8-8d31-72cd711d994e",

  "success": true,

  "errors": []

}

Session Cookies

The keys and encrypted records are never passed through the Remote API. The keys and encryption process all remain on the server in a user session with the results of the operations returned in the messages.

The vault uses sessions to keep track of users logged into the Remote API and provides a session id in a cookie when a user connects to the web site. The name of the session cookie is defined in the cvs/config.php configuration file for the application.

Most of the methods in the Remote API require an authenticated user and it will be necessary for any application that uses the API to pass the session cookie in the HTTP headers to identify the user's session.

Session GUID

When a user successfully authenticates the response will provide a temporary guid value that is associated with the current user session. The guid is used on the server to encrypt the keyring in memory when a session is active. This guid will be required to access any API methods that use the session keyring.

Methods

All requests must have a method parameter in the body of the request. The value of the method parameter must be the string specified in the method parameters in combination with any additional required parameters.

authenticate

The authenticate method is used to start a user session through the API. Successful authentication will return a guid value that must be used with the session cookie when calling methods that require an authenticated user.

Parameters

Request

Requirements

None

Parameter

Type

Description

method

string

"authenticate"

username

string

The account username.

password

string

The account password.

Response

Parameter

Type

Description

guid

string

A temporary unique identifier for the user.*

flags

integer

User flags that denote account type and permissions.

username

string

The account username.

errors

array

An array of error messages.

* The guid value in the response must be used in methods that require an authenticated user.

Example Request

{

    "method": "authenticate",

    "username": "bob",

    "password": "zZ9tTyy"

}

Example Response

{

  "guid": "7eedb701-31b8-4d5a-be8f-5ea171af23cc",

  "flags": "2",

  "username": "bob",

  "errors": []

}

* See the appendix for an explanation of the user flags.

logout

The logout method will end a user session and destroy the temporary guid.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"logout"

Response

Parameter

Type

Description

success

boolean

Success status.

errors

array

An array of error messages.

Example Request

{

    "method": "logout"

}

Example Response

{

  "success": true,

  "errors": []

}

changePassword

Change the account password. The guid value from an authenticate call will be required as well as passing the session cookie in the HTTP headers. The original user password is required in the oldPassword parameter to enable the decryption of the old keyring before re-encryption with the new password.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"changePassword"

oldPassword

string

The original account password.

newPassword

string

The new account password.

confirmNew

string

The new account password repeated to confirm.

Response

Parameter

Type

Description

success

boolean

Success status.

errors

array

An array of error messages.

Example Request

{

    "method": "changePassword",

    "oldPassword": "zZ9tTyy",

    "newPassword": "UiaksF",

    "confirmNew": "UiaksF"

}

Example Response

{

  "success": true,

  "errors": []

}

makePhrase

Make a random passphrase. This method generates a random passphrase that can be used as a strong passphrase for a key. The length of the passphrase is determined by the setting in cvs/config.php.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"makePhrase"

Response

Parameter

Type

Description

passphrase

string

The random passphrase.

errors

array

An array of error messages.

Example Request

{

    "method": "makePhrase"

}

Example Response

{

  "passphrase": "to7qerjVnqVN8eJHLGFfBAVc",

  "errors": []

}

makeKey

Change the account password. The guid value from an authenticate call will be required as well as passing the session cookie in the HTTP headers. Only Manager and Administrator accounts can create keys.

Parameters

Request

Requirements

Session Cookie, Manager or Administrator account

Parameter

Type

Description

method

string

"makeKey"

savePrivateKey

boolean

Set to true to save the private key in the vault. If set to false then the private key will be in the response and will not be saved in the vault.

recordsExpire

boolean

Set to true to have records encrypted with this key expire after their age exceeds the configured limit. Set to false if records encrypted with this key never expire.

recordsRemote

boolean

Set to true to allow saving of records with this key through the remote API. If set to false then this key can only be used through the PHP library methods.

keyName

string

The name of the key. This must be unique in the database.

passphrase

string

The passphrase required to enable the private key.

keyDescription

string

A brief description of this key.

Response

Parameter

Type

Description

privateKey

string

If the saveprivatekey parameter is set to false then this field will return the exported private key.

success

boolean

Success status.

errors

array

An array of error messages.

Example Request

{

  "method":"makeKey",

  "passphrase": "supersecret",

  "keyname": "Account Request",

  "keyDescription": "User account requests.",

  "savePrivateKey": true,

  "recordsExpire": true,

  "recordsRemote": false

}

Example Response

{

  "success": true,

  "errors": []

}

* Note that in this example the savePrivateKey parameter is set to true so the response does not include the privateKey value because the private key is saved in the vault.

toggleEnableKey

This method will toggle the enable flag on a key. If the key is disabled then it will become enabled and if it is enabled then it will become disabled.

Parameters

Request

Requirements

Session Cookie, Manager or Administrator account

Parameter

Type

Description

method

string

"toggleEnableKey"

name

string

The name of the key to toggle the enable flag.

Response

Parameter

Type

Description

success

boolean

Success status.

errors

array

An array of error messages.

Example Request

{

  "method": "toggleEnableKey",

  "name": "New Subscriptions"

}

Example Response

{

  "success": true,

  "errors": []

}

toggleRemoteKey

This method will toggle the remote save flag on a key. If the record remote save feature is disabled then it will be enabled and the key can then be used to save records through the Remote API. If the key has remote save enabled then it will become disabled and inaccessible for saveRecord requests through the Remote API.

Parameters

Request

Requirements

Session Cookie, Manager or Administrator account

Parameter

Type

Description

method

string

"toggleRemoteKey"

name

string

The name of the key to toggle the remote save flag.

Response

Parameter

Type

Description

success

boolean

Success status.

errors

array

An array of error messages.

Example Request

{

  "method": "toggleRemoteKey",

  "name": "New Subscriptions"

}

Example Response

{

  "success": true,

  "errors": []

}

getKeyList

Get a page from a paginated list of keys in the database. If the user making this request is an Associate then it will only return keys that also exist in the user's keyring.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"getKeyList"

page

integer

The page number to retrieve.

perPage

integer

The number of keys to include in each page

Response

Parameter

Type

Description

page

integer

The page number returned. This may be different from the page requested if the page requested does not exist.

pageCount

integer

The number of pages in the database.

keyCount

integer

The number of keys in the database.

keyList

array

An array of keys.

keyList[].name

string

The name of the key.

keyList[].description

string

The description of the key.

keyList[].havePrivateKey

boolean

Does the vault have the private key part of this key.

keyList[].usage

integer

The number of records in the vault that use this key.

keyList[].flags

integer

The status flags for this key.

errors

array

An array of error messages.

Example Request

{

  "method": "getKeyList",

  "page": 1,

  "perPage": 10

}

Example Response

{

  "page":1,

  "pageCount": 1,

  "keyCount": 4,

  "keyList": [

    {

      "name":  "Account Request",

      "description": "User account requests.",

      "havePrivateKey": true,

      "usage": 0,

      "flags": 11

    },

    {

      "name": "Balance Update",

      "description": "Update account balance.",

      "havePrivateKey": true,

      "usage": 14,

      "flags": 11

    },

    {

      "name": "New Subscriptions",

      "description": "New subscription requests.",

      "havePrivateKey": true,

      "usage": 10,

      "flags":  7

    },

    {

      "name": "Prospectus Query",

      "description": "Questions about prospectus.",

      "havePrivateKey": true,

      "usage": 18,

      "flags": 11

    }

  ],

  "errors": []

}

* See the appendix for an explanation of the key flags.

getKeyNameList

Get a list of the names for all keys in the database. If the user making the request is an Associate then they will only see the keys to which they have been given access through a saved keyring.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"getKeyNameList"

Response

Parameter

Type

Description

keyNameList

array

An array of strings holding the names of the keys.

errors

array

An array of error messages.

Example Request

{

  "method": "getKeyNameList"

}

Example Response

{

  "keyNameList": [

    "Balance Update",

    "Prospectus Query",

    "New Subscriptions",

    "Account Request"

  ],

  "errors":[]

}

deleteKey

Delete a key from the database.

Parameters

Request

Requirements

Session Cookie, Manager or Administrator account

Parameter

Type

Description

method

string

"deleteKey"

name

string

The name of the key to delete.

Response

Parameter

Type

Description

deleted

boolean

Status of delete success.

errors

array

An array of error messages.

Example Request

{

  "method": "deleteKey",

  "name": "Prospectus Query"

}

Example Response

{

  "deleted": true,

  "errors":[]

}

getKeyRingList

Get a list of the keys currently in the user's keyring. A user's keyring exists only on the server so any client application that needs to know what keys are available must query the server for a list of keys in the user's keyring.

Parameters

Request

Requirements

Session Cookie, guid from authenticate

Parameter

Type

Description

method

string

"getKeyRingList"

guid

string

The temporary user guid.

Response

Parameter

Type

Description

keyRingList

array

An array of key objects.

keyRingList[].name

string

The name of a key in the user's keyring.

errors

array

An array of error messages.

Example Request

{

  "method": "getKeyRingList",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5"

}

Example Response

{

  "keyRingList": [

    {

      "name": "New Subscriptions"

    },

    {

      "name": "Balance Update"

    }

  ],

  "errors":[]

}

saveUserKeyRing

Save the current user keyring into the user's account. When keys are added to a user's keyring they are added to the keyring in memory on the server. When the user signs out of the application the keyring is lost. The current keyring can be saved to the user's account so the next time the sign in they will have the same keyring restored in the session.

Parameters

Request

Requirements

Session Cookie, guid from authenticate

Parameter

Type

Description

method

string

"saveUserKeyRing"

guid

string

The temporary user guid.

Response

Parameter

Type

Description

success

boolean

The save success status.

errors

array

An array of error messages.

Example Request

{

  "method": "saveUserKeyRing",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5"

}

Example Response

{

  "success": true,

  "errors":[]

}

saveUserKeyRingToUser

Save the current user keyring into another user's account. The Associate accounts cannot save or modify their own keyring and must receive a keyring from another user who is authorized to create a keyring and save to other users. This will overwrite any existing keyring in the user's account.

NOTE: This will overwrite the user's current keyring in the database. When the user authenticates or reloads their keyring they will have this keyring that is saved to the user.

Parameters

Request

Requirements

Session Cookie, guid from authenticate, Manager or Administrator account

Parameter

Type

Description

method

string

"saveUserKeyRingToUser"

guid

string

The temporary user guid.

username

string

The account username where the keyring should be saved.

Response

Parameter

Type

Description

success

boolean

The save success status.

errors

array

An array of error messages.

Example Request

{

  "method": "saveUserKeyRingToUser",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "username": "tim"

}

Example Response

{

  "success": true,

  "errors":[]

}

addToKeyRing

Add an encryption key to the current keyring. This will take a key from the database, enable the private key using the provided credentials, and add this key to the user's current keyring in the current session. The key can then be used to read encrypted records in the database.

NOTE: Keys are only added to the keyring in memory. When the user session on the server ends the keyring is lost. The keyring must be saved to make the key permanent on the user's keyring.

Parameters

Request

Requirements

Session Cookie, guid from authenticate, Clerk or Manager or Administrator account

Parameter

Type

Description

method

string

"addToKeyRing"

guid

string

The temporary user guid.

name

string

The name of the key in the database to add to the keyring.

passphrase

string

The passphrase used to enable the private key.

privateKey

string

The exported private key if it is not saved in the database.

Response

Parameter

Type

Description

success

boolean

The add key success status.

errors

array

An array of error messages.

Example Request

{

  "method": "addToKeyring",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "name": "Account Request",

  "passphrase": "SlkoIml95JIgCY"

}

Example Response

{

  "success": true,

  "errors":[]

}

deleteKeyRingKey

Delete a key from the current user keyring. This will remove the key from the user's keyring in memory and the user will no longer be able to read records encrypted with that key.

NOTE: The key is only removed from the keyring in memory. When the user session on the server ends the keyring is lost. The keyring must be saved to permanently remove the key from the user's keyring.

Parameters

Request

Requirements

Session Cookie, guid from authenticate

Parameter

Type

Description

method

string

"deleteKeyRingKey"

guid

string

The temporary user guid.

name

string

The name of the key in the keyring to remove.

Response

Parameter

Type

Description

deleted

boolean

Status of delete success.

errors

array

An array of error messages.

Example Request

{

  "method": "deleteKeyRingKey",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "name": "Account Request",

  "passphrase": "SlkoIml95JIgCY"

}

Example Response

{

  "deleted": true,

  "errors":[]

}

reloadKeyRing

Reload the user keyring from the database account to the current user session. This will restore the saved keyring to the user session without the need to sign out and back in.

Parameters

Request

Requirements

Session Cookie, guid from authenticate

Parameter

Type

Description

method

string

"reloadKeyRing"

guid

string

The temporary user guid.

Response

Parameter

Type

Description

success

boolean

The add key success status.

errors

array

An array of error messages.

Example Request

{

  "method": "reloadKeyRing",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5"

}

Example Response

{

  "success": true,

  "errors":[]

}

getRecordList

Get a page from a paginated list of records in the database. This will include details about each record.

NOTE: Associate accounts will only see a list of records that match the keys in their current keyring. The list will not includes records they cannot read.

Parameters

Request

Requirements

Session Cookie, guid from authenticate

Parameter

Type

Description

method

string

"getRecordList"

guid

string

The temporary user guid. (only required for Associate accounts)

page

integer

The page number to retrieve.

perPage

integer

The number of records to include in each page

Response

Parameter

Type

Description

page

integer

The page number returned. This may be different from the page requested if the page requested does not exist.

pageCount

integer

The number of pages in the database.

recordCount

integer

The number of records in the database.

recordList

array

An array of records.

recordList[].id

string

The unique id for the record.

recordList[].created

string

A timestamp for the record creation date.

recordList[].description

string

A brief description of the record.

recordList[].keyName

string

The name of the key used to encrypt the record.

recordList[].lastRead

string

A timestamp for the last date the record was decrypted and read.

recordList[].expired

boolean

A status flag that indicates if the retention period has expired.

recordList[].retained

boolean

A status flag that indicates if the record is still in the must retain window and cannot be deleted.

errors

array

An array of error messages.

Example Request

{

  "method": "getRecordList",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "name": "New Subscriptions"

}

Example Response

{

  "page": 1,

  "pageCount": 6,

  "recordCount": 59,

  "recordList": [

    {

      "id": "a8562d2a-a7a1-4fe4-a0fe-3eb231f9411d",

      "created": "2015-10-07 03:07 PDT",

      "description": "New Subscription From: Bob Toad",

      "keyName": "New Subscriptions",

      "lastRead": null,

      "expired": false,

      "retained": false

    },

… some records removed to make documentation brief ...

    {

      "id": "eee39179-6831-44db-a623-ff165693922d",

      "created": "2015-10-07 03:06 PDT",

      "description": "New Subscription From: Bob Toad",

      "keyName": "New Subscriptions",

      "lastRead": null,

      "expired": false,

      "retained": false

    }

  ],

  "errors":[]

}

* See the appendix for an explanation of the key flags.

saveRecord

Save a new record in the database using one of the encryption keys.

NOTE: The key selected for encryption must have the Remote Record Save flag enabled.

Parameters

Request

Requirements

None

Parameter

Type

Description

method

string

"saveRecord"

keyName

string

The name of the encryption key to use.

description

string

A brief description that will be used to identify the record.

data

mixed

The content that will be encrypted. This may be a simple string, a complex JSON object, or some other serialized data object.

Response

Parameter

Type

Description

success

boolean

The save record success status.

errors

array

An array of error messages.

Example Request

{

  "method": "saveRecord",

  "keyName": "New Subscription",

  "description": "Subscription Request from Bob Jenson",

  "data": "Subscription Request\nName: Bob Jenson\nEmail: bobj@mail.com"

}

Example Response

{

  "success": true,

  "errors":[]

}

readRecord

Read an encrypted record from the database. This method is used to read and decrypt records using the keys in the current user's keyring or using the key credentials passed in the request.

NOTE: There are two methods of reading encrypted records from the database.

1) Pass the guid value and use the keyring in the current user session.

2) Provide the passphrase to the private key associated with the record and the exported private key if it is not saved in the database.

Parameters

Request

Requirements

None

Parameter

Type

Description

method

string

"readRecord"

id

string

The unique id of the record in the database.

guid

string

The temporary user guid. This parameter is required when using the keyring for a currently authenticated user.

passphrase

string

The passphrase for the private key required to decrypt the record. This is only required when not using the current user keyring.

privateKey

string

The exported private key if not saved in the database. This is only required when not using the current user keyring and the key in the database does not include the private key.

Response

Parameter

Type

Description

readRecord

object

The record read and decrypted.

readRecord.description

string

The brief description of the record.

readRecord.data

mixed

The decrypted record content.

readRecord.id

string

The unique id of the record.

errors

array

An array of error messages.

Example Request

{

  "method": "readRecord",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "id": "a8562d2a-a7a1-4fe4-a0fe-3eb231f9411d"

}

Example Response

{

  "readRecord": {

    "description": "New Subscription From: Bob Toad",

    "data": "Client: Bob Toad\nEmail: bobt@bobtoad.org",

    "id": "a8562d2a-a7a1-4fe4-a0fe-3eb231f9411d"

  },

  "errors":[]

}

deleteRecord

Delete a record from the database. The record will be deleted if the user has the correct permissions, has the encryption key that was used to save the record, the record create date is past the required retention window, and the record has been read by one of the system users.

NOTE: Administrator users can delete any record in the system without restriction.

Parameters

Request

Requirements

Session Cookie, guid from authenticate, Clerk or Manager or Administrator account

Parameter

Type

Description

method

string

"deleteRecord"

id

string

The unique id of the record in the database.

guid

string

The temporary user guid.

Response

Parameter

Type

Description

deleted

boolean

Status of delete success.

errors

array

An array of error messages.

Example Request

{

  "method": "deleteRecord",

  "guid": "8a5c911f-2b20-40e3-86ea-a1fa442ab1e5",

  "id": "a8562d2a-a7a1-4fe4-a0fe-3eb231f9411d"

}

Example Response

{

  "deleted": true,

  "errors":[]

}

getUserList

Get a list of user names in the database. An Administrator user will receive a list of all usernames while a Manager will only receive a list of Associate and Clerk usernames.

Parameters

Request

Requirements

Session Cookie, Manager or Administrator account

Parameter

Type

Description

method

string

"getUserList"

guid

string

The temporary user guid.

Response

Parameter

Type

Description

userList

array

An array of user objects.

userList[].username

string

The account username.

userList[].flags

integer

The account status flags.

errors

array

An array of error messages.

Example Request

{

  "method": "getUserList"

}

Example Response

{

  "userList": [

    {

      "username": "admin",

      "flags": 4

    },

    {

      "username": "bob",

      "flags": 2

    },

    {

      "username": "tim",

      "flags": 8

    }

  ],

  "errors":[]

}

* See the appendix for an explanation of the user flags.

saveUser

Save a new or updated user account to the database.

Parameters

Request

Requirements

Session Cookie, Administrator account

Parameter

Type

Description

method

string

"saveUser"

olduser

string

The original username when editing a user. Leave blank when creating a user.

username

string

The new username or the same value as olduser if editing a user and not changing the username.

password

string

The user password. Leave blank when editing a user and the password is not changed.

flags

integer

The user account status flags.

Response

Parameter

Type

Description

success

boolean

The save user success status.

errors

array

An array of error messages.

Example Request

{

  "method": "saveUser",

  "olduser": "",

  "username": "mary",

  "password": "changeme",

  "flags": 1

}

Example Response

{

  "success": true,

  "errors":[]

}

deleteUser

Save a new or updated user account to the database.

Parameters

Request

Requirements

Session Cookie, Administrator account

Parameter

Type

Description

method

string

"deleteUser"

username

string

The username of the account to delete.

Response

Parameter

Type

Description

success

boolean

The delete user success status.

errors

array

An array of error messages.

Example Request

{

  "method": "deleteUser",

  "username": "mary"

}

Example Response

{

  "success": true,

  "errors":[]

}

getLogList

Get a page from a paginated list of log events in the database.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"getLogList"

page

integer

The page number to retrieve.

perPage

integer

The number of log events to include in each page

Response

Parameter

Type

Description

page

integer

The page number returned. This may be different from the page requested if the page requested does not exist.

pageCount

integer

The number of pages in the database.

logCount

integer

The number of log events in the database.

logList

array

An array of log events.

logList[].timestamp

string

The timestamp for the log event.

logList[].username

string

The username for the account associated with this event.

logList[].event

string

The event message.

errors

array

An array of error messages.

Example Request

{

  "method": "getLogList",

  "page": 1,

  "perPage": 10

}

Example Response

{

  "page": 1,

  "pageCount": 11,

  "logCount": 103,

  "logList": [

    {

      "timestamp": "2015-10-09 15:20:35",

      "username": "admin",

      "event": "Deleted user mary."

    },

… some records trimmed from response to make documentation brief ...

    {

      "timestamp": "2015-10-09 15:12:23",

      "username": "admin",

      "event": "Created user mary."

    }

  ],

  "errors":[]

}

exportLogList

Export the log list to a CSV string. This method is used to create a backup archive of the log events. It will take all the log events from the beginning of the log up to the recent day specified and export them into a CSV formatted string that can be stored in a CSV file and/or imported into a spreadsheet application.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"exportLogList"

upToDays

integer

Export from beginning up to X days from the current date.

Response

Parameter

Type

Description

logCSV

string

The exported log list in CSV format.

errors

array

An array of error messages.

Example Request

{

  "method": "exportLogList",

  "upToDays": 7

}

Example Response

{

  "logCSV": "Timestamp,Username,Event\n\"2015-10-13 06:43:40.285833\",a … truncated ...

  "errors":[]

}

deleteLogList

Delete the log list. This method is used to delete the log events. It will delete the log events from the beginning of the log up to the recent day specified.

Parameters

Request

Requirements

Session Cookie

Parameter

Type

Description

method

string

"deleteLogList"

upToDays

integer

Delete from beginning up to X days from the current date.

Response

Parameter

Type

Description

deleted

boolean

Delete success status.

errors

array

An array of error messages.

Example Request

{

  "method": "deleteLogList",

  "upToDays": 7

}

Example Response

{

  "deleted": true

  "errors":[]

}

Appendix

User Flags

The user flags are based on binary bit values that make it easy to check for a specific user flag using bitwise operators. As an example, if the variable flags contains a users's flag settings and you want to check the user's flags to see if the user is an Administrator you can use the statement (flags & 4) and this will return a value of 0 if it is not an Administrator and 4 if it is an Administrator.

User Flag Values

Constant

Value

USER_CLERK

1

USER_MANAGER

2

USER_ADMIN

4

USER_ASSOCIATE

8

Key Flags

The key flags are based on binary bit values which makes it possible to use bitwise operators to check whether a flag bit is set or clear.

Key Flag Values

Constant

Value

KEY_SAVE_PKEY

1

KEY_RECORDS_EXPIRE

2

KEY_REMOTE

4

KEY_ENABLED

8