REST API Reference
Managers can create and delete API tokens using the tiCrypt Audit
interface. The tokens allow certain actions to be executed from
any programming or scripting language that supports GET or
POST requests and can set the x-access-token header to the secret
generated by the token creation process.
Token-based authentication supports only functionality that does not require administrator privileges. Management activities (including creating tokens) require session-based authentication, i.e. the tiCrypt Audit front-end.
You can try the API using the curl command. Token-based
authentication looks like
curl -X GET "https://audit.ex.com/.." -H "x-access-token:my_secret".
Each supported route includes an example of this command.
A token secret always consists of 22 alphanumeric characters followed by
==8wdpQhekwrCCl8h8/gbeaA==.
Information Routes
These routes provide general information about the system or its capabilities.
Information routes require either token-based or session-based authentication. The only exception is the GET /info route.
Some of these routes return objects; others return 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 the list of supported parameters
GET /queries/params
Ex: curl -X GET https://audit.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 GET https://audit.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 the list of supported queries
GET /queries/list
Ex: curl -X GET https://audit.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 the list of supported reports
Projects can be parametrized by an object (the report is built for that object).
GET /reports/list
Ex: curl -X GET https://audit.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 the list of supported alert types
GET /alerts/list
Ex: curl -X GET https://audit.ex.com/alerts/list
Returns: map from alertID to 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 extract information from the system. The
endDate parameter is present in all routes. Most routes also have a
startDate and other relevant parameters.
The dates are always in the YYYY-MM-DD format (i.e. the ClickHouse
date format).
To include all past data, set startDate to
1970-01-01 and endDate to 2037-12-31.
All of these routes require authentication. The x-access-token header
must be set to the secret generated by the token creation process.
Get alerts triggered
This query returns the list of alerts triggered in a given period. 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. This route retrieves information about such objects.
The EndDate specifies the point in time with respect to which the
information is reconstructed (the information changes over time).
The body of the POST request is an array of strings specifying the IDs for
which to retrieve information. Some object types support
an empty array, i.e. [], and return information on all objects.
Try passing -d "[]" to curl to see whether information on all objects
is returned.
POST /objects/{Type}/{EndDate}
Body: array of strings, possibly empty, indicating 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 the indicated type
Run query
This route executes queries.
To interpret the result of a query, use the information returned
by /queries/list for that 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 an Excel spreadsheet for any report supported by the system (either built-in or custom).
This route has two forms, depending on whether the report requires an extra parameter.
The /reports/list route returns the list of available reports.
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