Skip to main content

Token based REST API

As a manager, using the tiCrypt Audit interface, API tokens can be created and deleted. The tokens allow execution of certain actions from any programming or scripting language that supports simple GET or POST requests and can set the header x-access-token to the secret generated by the token creation process.

Only functionality that does not require administrator privileges is supported. Management activities (including creating tokens) can only be performed using session-based authentication, i.e. using the tiCrypt Audit front-end.

A simple way to try the API is using the curl command. Toke based authentication looks like curl -X GET "https://audit.ex.com/.." -H "x-access-token:my_secret". We will provide an example of this command for each supported route.

A token secret is always made 22 alpha-numeric characters followed by ==, e.g. 8wdpQhekwrCCl8h8/gbeaA==

Information routes

These routes provide general information about the system or its capabilities.

These routes do not require authentication. Passing the authentication token will not result in an error.

Some of these routes return objects, others lists of objects or maps from ids to objects. The type is indicated in the Returns: notes.

General system information

GET /info
Ex: curl -X GET https://audit.ex.com/info
Returns: object of the form:

{
"version": "the_version_number",
"name": "tiCrypt Audit"
}

Get list of supported parameters

GET /queries/params
Ex: curl -X https://autid.ex.com/queries/params
Returns: list of objects of the form

{
"id": "param_id",
"default": "default value",
"desc": "param description",
"type": "param_type"
}

Get the list of tags

GET /tags/list Ex: curl -X https://autid.ex.com/tags/list
Returns: list of objects of the form

{
"id": "tag_id",
"name": "tag name",
"desc": "tag description",
"cat": "tag category",
"pri": numeric_tag_priority
}

Get list of supported queries

GET /queries/list
Ex: curl -X https://autid.ex.com/queries/list
Returns: list of objects of the form

{
"id": "query_id",
"name": "Query name",
"desc": "Query description",
"tags": [ "tag_1", "tag_2", .. ],
"returnTypes": [ "Type1", "Type2", ... ],
"returnNames": [ "Out1", "Out2", ... ],
"params": [
{
"id": "param_id",
"name": "Param name",
"default": value,
"desc": "param description",
"type": "ParamType",
}, ...
],
"charts": [ ... ]
}

Get list of supported reports

Projects can be parametrized by an object (the report will be build for that object).

GET /reports/list
Ex: curl -X https://autid.ex.com/reports/list
Returns: list of objects of the form

{
"id": "project_id",
"name": "project name",
"desc": "project description",
"objType": "type_of_object_parameter",
"objParam": "id_of_object_parameter",
"queryIDs": [
"query_id": ["qID1", "qID2", ... ],
"queryParams": [
{
"param1": "value", ...
}, ...
]
]
}

Get list of supported alert types

GET /alerts/list
Ex: curl -X https://autid.ex.com/alerts/list
Returns: map from alertID to of objects of the form

{
"name": "name of the alert",
"severity": "info|low|medium|high|critical",
"sType": "Extra information type",
"sField": "Field containing the extra information"
}

Data routes

These routes allow information to be extracted from the system. The endDate paramete is present in all the routes. Most routes also have a startDate and other relevant paramenters.

The dates are always in the YYYY-MM-DD format (i.e. the Clickhouse date format)

If you want to include all the past data, set startDate to 1970-01-01 and endDate to 2037-12-31.

All of these routes require authentication. Header x-access-token must have as value the secret generated by the token creation process.

Get alerts triggered

This query returns the list of alerts triggered in a given period of time. GET /alerts/{StartDate}/{EndDate}
Ex: curl -X GET https://audit.ex.com/alerts/1970-01-01/2030-01-01 -H "x-access-token:my_secret"
Returns: list of objects of the form

{
"date": "date in YYYY-MM-DD format",
"timestamp": Unix time,
"type": "type as returned by /alerts/list",
"info": SpecificAlertInfo
}

Get object information

Most of the queries and reports express the results in terms of ObjectID values. Information about such objects can be obtained using this route. The EndDate specifies the point in time w.r.t. which the information is reconstructed (the information changes in time).

The body of the post is an array of strings, specifying the IDs for which the information needs to be retrieved. Some object types support an empty array, i.e. [], and will return information on all objects.

Try to pass -d "[]" to curl to see if the information on all objects is returned.

POST /objects/{Type}/{EndDate}
Body: array of strings, possibly empty indicatinng which objects to retrieve
Ex: curl -X POST https://audit.ex.com/objects/UserID/2030-01-01 -H "x-access-token:my_secret" -d "[]"
Returns: list of objects of type indicated

Run query

This route allows queries to be executed.

To be able to interpret the result of a query, the information returned by /queries/list has to be used for the specific query

POST /queries/{QueryID}/{EndDate} Body: map from parameter name to value for all parameters
Ex: curl -X POST https://audit.ex.com/queries/UserStats/2030-01-01 -H "x-access-token:my_secret" -d "\"startDate\": \"1970-01-01\""
Returns: array of rows. Each row is an array of values.

Generating Excel Reports

tiCrypt Audit can generate Excel reports for any reports supported by the system (either built-in or custom).

There are two forms for this route depending on whether the report requires an extra parameter

The list of the available reports can be retrieved using the route /reports/list

These routes return generated files not JSON objects

GET /reports/{ReportID}/{StartDate}/{EndDate}
GET /reports/{ReportID}/{StartDate}/{EndDate}/{ObjectID}
Ex: curl -X GET `https://audit.ex.com/Overview/1970-01-01/2030-01-01 -H "x-access-token:my_secret" -o report.xslx
Returns: the content of the Excel spreadsheet file