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:

• Application and Workspaces Updates

• Configuration Updates

• Data Access Events

• User Access, Admin Access, and Security

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:

 $ 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:

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.

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:

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

//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"
    }
  }
}

The logs are returned as a ZIP file. Download and unzip the file to see the events that occurred during the date and time range you requested.

Resources

• Endpoint Reference

• Application and Workspaces Updates Logs Reference

• Configuration Updates Logs Reference

• Data Access Events Logs Reference

• User Access and Security Logs Reference