Audit Logs

Overview

An audit log, also called an audit trail, is a record of events and changes in your environment. Examples include logins, logouts, module creation and saves, and so on. Audit logs capture these events by recording the activity performed, who performed the activity, and how the system responded.

Audit logs are also critical for proving compliance with HIPAA and PCI DSS regulations. They serve as an official record that you can use to prove you're in compliance with the law. Sometimes, it’s necessary to share logs with auditors on a regular basis—especially if an issue occurs. Audit logs ensure you protect your business from fines and penalties.

TIP  To learn more about the Audit Logs API, view our Get API Logs documentation.

What You'll Learn

In this article, you'll learn how to request data and understand the most common data.

What to Expect from Audit Logs

Unqork audit logs are organized into the following categories:

But, before you can request audit logs, ensure you're authenticated to use the Unqork API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (application programming interface).

Authentication

Unqork's API implements the OAuth 2.0 Password Grant. Access using OAuth2 Password Grant can be enabled for all users in Environment Administration. Once enabled, all Unqork users can apply their Unqork username and password to retrieve an access token.

TIP  To learn more about authenticating to the Unqork API, see our API Authentication documentation.

To use API resources, you must first retrieve an access token by POSTing your credentials to the access token URL. To retrieve an access token, enter the following curl command in your computer's terminal or command line tool:

Copy
 $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d "grant_type=password&username={username}&password={password}"

Modify the following information with your own:

  • Replace {xyzfinancial} with your environment domain.

  • Replace {username} with your Unqork environment username.

  • Replace {password} with your Unqork environment password.

This request returns an access_token that you can retain and use for audit log requests.

NOTE  Access tokens expire after one hour. After it expires, you must repeat the above steps to request a new one.

Requesting Audit Logs

Now that you have your access token, you can begin requesting audit logs. Enter the following curl command in your computer's terminal or command line tool:

Modify the following information with your own:

Copy
curl -H 'Authorization: Bearer {access_token}' 'https://xyzfinactial.unqork.io/api/graphql' \
-H 'Content-Type: application/json' \
--data '{"query":" { instrumentation { auditLogs { listAuditLogs( startDatetime: \"2023-06-12T16:30:00Z\", endDatetime: \"2023-06-12T16:45:00Z\", schemaVersion: \"1.0\") { logLocations  } } } }","variables":{}}'

Modify the following information with your own:

  • Replace {access_token} with the access token you retrieved in the previous step.

  • Replace {xyzfinancial} with your environment domain.

  • Replace the example {startDatetime} with the starting time you want to retrieve audit logs.

  • Replace the example {endDatetime} with the ending time you want to retrieve audit logs.

WARNING  The time range cannot exceed one hour. Also, ensure the seconds in your UTC Cross Site Scripting attacks vulnerability used by malicious entities to bypass the access controls of a website. start and end times are always 00.

TIP  To learn more about the event logs and their responses, see the Resources section of this article. It's important to note that these resources are still in development. Visit regularly to view new response data.

Viewing Common Response Data

When viewing the beautified response, there are several data fields common to each event. The unique data fields for each event display in the attributes and priorAttributes object. These include:

Element Description Type

date

The date and time (UTC) when the event occurred.

String

messageType

The message type. This event displays a system-event message type.

String

schemaVersion

The schema version controlling the JSON structure of the output.

String

timestamp

The exact date and time (UTC) when the event occurred.

String

eventType

The event type. This event is a designer-action type.

String

category

The event category. For example, access-management, user-access, user-management, and so on.

String

action

The action taken by the user. For example, add-designer-user, designer-user-login, modify-designer-role, and so on.

String

source

The API source. The source for this event is designer-api.

String

tags

All tags associated with this event.

String

object↴

An object of event detail data.

Object

type

A description of the recorded event.

String

identifier↴

An object detailing event identifier data.

Object

type

The identifier that triggered this event. For example, entering a name in a field or creating a session.

String

value

The value associated with the identifier.

String

attributes↴

An object of event attributes.

Object

outcome↴

An object detailing the success or failure of the recorded data. The outcome can be “success” or “failure”. If it is a failure, then a failure reason is included. Possible failure values are “authentication”, “authorization”, or “unknown”. Any post-authentication failure displays “unknown”. Failures also display an error string explaining why it occurred. For Unqork API failures, view the following documentation: https://developers.unqork.io/.

Object

type

This value is "success" if the recorded event was successful.

String

actor↴

An object detailing the requestor of the event data.

Object

type

The requestor type.

String

identifier↴

An object of requestor detail data.

Object

type

The identifier type that identified the requestor.

String

value

The requestor's unique identifier.

String

attributes

All attributes associated with the requestor.

String

context↴

An object detailing the environment, host, user agent of the requestor.

Object

environment

The environment where the data was requested.

String

sessionId

The unique session identifier of the request.

String

clientIp

The client IP address of the requestor.

String

protocol

The protocol performed to request the data.

String

host

The domain where the data was requested.

String

userAgent

The user agent of the requestor.

String

Below is an example of what you should expect in a response:

Copy
//Example Response//
{
  "date": "2022-12-19T19:46:38.000000Z",
  "messageType": "system-event",
  "schemaVersion": "1.0",
  "timestamp": "2022-12-19T19:46:38.338Z",
  "eventType": "designer-action",
  "category": "access-management",
  "action": "delete-designer-role",
  "source": "designer-api",
  "tags": {},
  "object": {
    "type": "designer-role",
    "identifier": {
      "type": "name",
      "value": "Unqork User Name"
    },
    "attributes": {},
    "outcome": {
      "type": "success"
    },
    "actor": {
      "type": "user",
      "identifier": {
        "type": "user-id",
        "value": "unqork-user@unqork.com"
      },
      "attributes": {}
    },
    "context": {
      "environment": "training-staging",
      "sessionId": "8a83187f-40cb-4bd2-a0fc-8dd3987a771a",
      "clientIp": "73.33.37.100",
      "protocol": "https",
      "host": "training.unqork.io",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36"
    }
  }
}

Resources