Logs API

The Logs API is a REST API that provides programmatic access to the log streaming functions in STA. Use the Logs API to retrieve access and authentication logs directly from within your custom application. Alternatively, you can use the SafeNet Logging Agent to automatically retrieve the logs.

You can retrieve the logs only for the virtual server that is associated with the API key.

The Logs API can retrieve the logs within minutes after they are produced. The logs are returned as JSON objects, with one JSON object per event log entry. Each log entry includes the account name and the tenant code (the unique identifier for a virtual server).

To use any of the REST APIs for STA, you need an API key for authentication.

Logs API reference

The API reference documentation describes the endpoints, methods, requests, and responses for all of the REST APIs for STA. You can find the link for your API reference documentation on the STA Access Management console in Settings > API Keys:

`https://api.< STA *server*>.com/swagger/index.html`

Date and time parameters

The Logs API includes the following parameters for specifying the date and time period for logs:

• Since: The date and time in the log file from which you want log retrieval to start. By default, this is 24 hours before the Logs API function call.

• Until: The date and time in the log file at which you want log retrieval to stop. By default, this is the current date and time.

The time period must be formatted as follows: 

• Without the time: yyyy-mm-ddZ

  Example: 2020-01-16Z.

• Including the time: yyyy-mm-ddThh:mm:ss.fffZ

  Example: 2020-01-16T23:59:00Z

  Where: 

  • The default time is 00:00:00.000, in 24-hour notation, for the specified date.

  • T separates the date and time parameters. It's required only if the time is specified.

  • fff (optional) represents the milliseconds specified for the time parameter

  • Z (mandatory) represents the coordinated universal time (UTC).

  • Any unspecified time units are assumed to be 0. For example, 23:45Z is interpreted as 23:45:00.000Z.

Pagination links in logs

Logs that are sent in response to an API request (using either the Logs API or the SafeNet Logging Agent) include markers that delimit each page of logs. These markers are included with the self, next, and skip links sent by STA.

"links": {
    "first": "https://server/api/v1/tenants/abcdef/logs?since=2019-12-19T04:22:16.718Z&until=2019-12-19T12:22:16.718Z",
    "self": "https://server/api/v1/tenants/abcdef/logs?since=2019-12-19T04:22:16.718Z&until=2019-12-19T12:22:16.718Z&marker=1234",
    "next": "https://server/api/v1/tenants/abcdef/logs?since=2019-12-19T04:22:16.718Z&until=2019-12-19T12:22:16.718Z&marker=4567",
    "skip": "https://server/api/v1/tenants/abcdef/logs?since=2019-12-19T04:22:16.718Z&until=2019-12-19T12:22:16.718Z&marker=8910"
  },

• The self link retrieves the logs for the current page.

• The next link retrieves the next page of logs.

• The skip link appears on the last page of the logs response. It provides a direct link to the next series of logs to retrieve.

Use the skip link to ensure that you don't miss any logs. In comparison, using a new set of Since and Until parameters could leave some time gaps between logs.

Note

When using the SafeNet Logging Agent, the agent takes care of receiving the logs over multiple pages in response to the API call it makes, and of streaming these logs over syslog messages (where one syslog message includes one STA log).

Log streaming with the Logs API

The Log Streaming settings includes the log streaming status, which lists one entry for each API key from which at least one Logs API call was made.

It also includes the two options for configuring log streaming: using SafeNet Logging Agent or the Logs API. The Logs API option takes you to the API Keys screen, where you can get an API key, and find the links to access the API and the API reference documentation.

• On the STA Access Management console, select Settings > Log Streaming.