Authentic8 API Reference Guide


Summary

The Authentic8 API provides a set of commands to enable a customer to interact with our data in an automated fashion. The Authentic8 API currently supports commands for log extraction.


Use

To invoke the API, a set of commands is posted to an Authentic8 API host via https.


The Authentic8 API server is: extapi.authentic8.com

 

JSON structures should be POSTed to: https://extapi.authentic8.com/api/

 

The POST Content-Type should be application/json.

 

The commands are in the form of a JSON array of objects; each object should have a “command” item; the rest are arguments to the command:

 

[

 { “command”: <command>, “arg1”: <value>, “arg2”: <value> },

 [...]

 { “command”: <command>, “arg1”: <value>, “arg2”: <value> }

]

 

The return is a JSON array of responses, one per command. The responses will be returned in the order that the commands were sent. All commands will accept a “command_id” argument; if present, this id will be present in the response for that command.


Auth tokens

An Authentication Token is a security credential required for programmatic access to the Authentic8 API. Auth tokens are issued by Authentic8 support. An auth token is tied to an existing admin account, and the scope of operations available with an auth token will be restricted to what would be available in the admin console for that admin.  Auth tokens also have a role which limits the possible operations.  For instance, the log role only allows log extraction, not user deletion or similar operations that the admin could do from the admin console.


Org names

Org names within the Authentic8 system are not required to be unique (they are required to be unique within a single parent org). In most cases, this will not be an issue; a simple org name is acceptable as long as it is not ambiguous relative to the admin specified in the auth token. If there is ambiguity, an org path may be specified.

 

Org paths are slash-separated org names (slashes may be escaped by backslash if there is a slash in an org name). Org paths do not need to be complete; each element only needs to disambiguate the next element (so elements may be skipped).


Log Extraction


Commands

 

setauth

arguments: data

Sets the authorization token to be used in subsequent API commands. An authorization token must be present and must be the first command in the JSON array of commands sent to the API (see the Examples section for a sample).

 

extractlog

arguments: start_seq end_seq org type limit

Extracts log data of type for the referenced org.

 

start_seq and optional end_seq can be used to retrieve subsets of the log data. start_seq of 0 and no end_seq will return all available log data.

 

At most, 1,000 log items will be returned per request.  In the response, there is a boolean, is_more, and a number, next_seq, which let you page through the results when there are more than can be returned in a single request.  If you prefer fewer log lines per request, you can set the limit argument to the request to a number.

 

The Authentic8 API allows extraction of the following log types:

 

Type

Description


ADMIN_AUDIT


Audit logs for administrator configuration activities


AUTH


Logs related to Authentic8 Silo authentication events


COOKIES


Logs related to browser cookies

Note: ONLY logged if using log encryption


DOWNLOAD


Logs related to file downloads


UPLOAD


Logs related to file uploads


POST DATA


Logs related to HTTP POSTs

Note: ONLY logged if using log encryption


SESSION


Logs related to browser session information


ENC


Encrypted logs

Note: When encryption is enabled, discrimination between different log types is not possible during extraction, since logs are encrypted with the customer’s public key. The customer will be able to identify log types in the decrypted data.


URL


Logs related to browser navigation


BLOCKED URL


Logs related to sites/urls prevented from Category or Domain Filtering policies


LOCATION CHANGE


Logs related to address changes in the location bar (URL bar).  

Note: Also tracks Google.com searches when Enter/Return key submitted on the search form


TRANSLATION  


Logs related to web site page content or selection of content translated  


A8SS  


Logs related to Cloud Storage activities

 


The results will include the next_seq and is_more fields to help identify the last logs retrieved.  If is_more is false, that means there are no more logs that fit the criteria at the moment of the request.  More may appear at any moment.

 

If extracting ENC log type, the results will include the customer assigned key_name to help identify the public key that was used to encrypt the logs.


Examples

A sample of commands with responses.

 

[

{"command": "setauth", "data": "<AuthToken>"},

{"command": "extractlog", "start_seq": 0, "org": "<OrgName>", "type": "ENC"}

]

 

Results

{

 "next_seq": 3233683,

 "logs": [

   {

     "key_name": "SILOTest",

     "enc": "AegpLEeh9mseUW8Gc7eop03cZ/9kLiHtvSHClOUop4DR/PRMIGXmiFATlI7/O2pK1ZxT69KLoxNzpvvgXCgYSEENRZKoVLJknGGVSbMK/NhjKFOXxdxMrLNFijJTsJ2qICt/2EkSRLxbFjXiSAEGBLmFqqq3gt3Je4flo9mpRViNxWHmYY8L4KPbHKYbp8AJeCcjWlldvnRTlXh/biKbBu9Cn85TbyUak+MVmPofKHjYAj0KivPd2DsISGSV0RRw2gY5ymIDLoNaS4wchMQUmwxo3duHF+r+L0GXo4fkgRrR360c4TQ7qA2HykQT",

     "type": "ENC",

     "create_ts": 1407538630.06108,

     "seq_id": 3233682

   }

 ],

 "is_more": false

}

 

Note that the fields that get returned are different, depending on the type of  logs getting pulled:

 

[

{"command": "setauth", "data": "<AuthToken>"},

{"command": "extractlog", "start_seq": 0, "org": "<OrgName>", "type": "URL"}

]

 

returns:

 

{

 "next_seq": 3204202,

 "logs": [

   {

     "domain": "www.java.com",

     "user_id": "466...3d4",

     "response_headers": "Server: Sun-Java-System-Web-Server/7.0\r\nContent-Type: text/html;charset=UTF-8\r\nContent-Encoding: gzip\r\nVary: accept-encoding\r\nContent-Length: 2516\r\nDate: Tue, 01 Jul 2014 20:19:33 GMT\r\nConnection: keep-alive\r\n",

     "seq_id": 3204201,

     "response_code": 200,

     "org_id": "509...0c0",

     "session_id": "399...aa9",

     "headers": "Host: www.java.com\r\nUser-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:29.0) Gecko/20100101 Firefox/29.0 Authentic8/1.0\r\nAccept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8\r\nAccept-Language: en-US,en;q=0.5\r\nAccept-Encoding: gzip, deflate\r\nDNT: 1\r\nConnection: keep-alive\r\n",

     "create_ts": 1404245973.396193,

     "response_size": 2516,

     "path": "/en/download/installed.jsp",

     "scheme": "http",

     "type": "URL"

   }, ...

 ],

 "is_more": true

}