Token-based REST API
As a manager, using the tiCrypt Audit interface, API tokens can be
created and deleted. The tokens allow the 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. Token-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 of 22 alpha-numeric characters followed by
==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 list 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 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 the 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 the list of supported reports
Projects can be parametrized by an object (the report will be built 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 the 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
parameter 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 a value 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. 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 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 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