/Docs

Audit Log API

This page contains the APIs that are used to manage the Audit Log. Here are the APIs:

Add an Entry to the Audit Log#

This API allows you to insert an Audit Log. Generally, Audit Logs are created automatically whenever an admin does something from the FusionAuth UI. However, you can use this API to insert Audit Logs directly if you need.

Request#

API Key Authentication
Create an Audit Log
POST/api/system/audit-log

Request Body#

auditLog.dataObjectoptional

An object that can hold additional details of an audit log.

auditLog.newValueStringoptional

Intended to be utilized during a change to record the new value.

auditLog.oldValueStringoptional

Intended to be utilized during a change to record the old value prior to the change.

auditLog.reasonStringoptional

Intended to be utilized during a change to indicate the reason for the modification.

auditLog.tenantIdUUIDoptionalAvailable since 1.65.0

The Id of the Tenant associated with this Audit Log. This field will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

auditLog.insertUserStringrequired

The user that took the action that is being written to the Audit Logs. We suggest you use email addresses for this field.

auditLog.messageStringrequired

The message of the Audit Log.

Example Request JSON

{
  "auditLog": {
    "data": {
      "externalId": "_applicationA"
    },
    "newValue:": "{\"name\": \"bar\"}",
    "oldValue": "{\"name\": \"foo\"}",
    "reason": "Because I like to change things.",
    "insertUser": "user@fusionauth.io",
    "message": "Example audit log"
  }
}

Response#

The response for this API does not contain a body. It only contains a status code.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Retrieve an Audit Log#

Request#

API Key Authentication
Retrieve an Audit Log by Id
GET/api/system/audit-log/{logId}

Request Parameters#

logIdLongrequired

The unique Id of the Audit Log to retrieve.

Response#

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

auditLog.dataObject

Additional details of an audit log.

auditLog.newValueString

The new value of a changed object.

auditLog.oldValueString

The previous value of a changed object.

auditLog.reasonString

The reason why the audit log was created.

auditLog.tenantIdUUIDAvailable since 1.65.0

The Id of the Tenant associated with this Audit Log. This field will be null for instance-scoped audit logs. The associated audit-log.create event will be delivered as a tenant-scoped event.

auditLog.idLong

The Audit Log unique Id.

auditLog.insertInstantLong

The instant when the Audit Log was created.

auditLog.insertUserString

The user that created the Audit Log.

auditLog.messageString

The message of the Audit Log.

Example JSON Response

{
  "auditLog": {
    "data": {
      "externalId": "_applicationA"
    },
    "newValue:": "{\"name\": \"bar\"}",
    "oldValue": "{\"name\": \"foo\"}",
    "reason": "Because I like to change things.",
    "id": 3,
    "insertInstant": 1471796483322,
    "insertUser": "user@fusionauth.io",
    "message": "Changed Application"
  }
}

Search the Audit Log#

This API allows you to search and paginate through the Audit Logs.

Request#

API Key Authentication
Searches the Audit Logs using the given search criteria
GET/api/system/audit-log/search?message={message}&start={start}&end={end}&user={user}

When calling the API using a GET request you will send the search criteria on the URL using request parameters. In order to simplify the example URL above, not every possible parameter is shown, however using the provided pattern you may add any of the documented request parameters to the URL.

Request Parameters#

endLongoptional

The end instant of the date/time range to search within.

messageStringoptional

The string to search in the Audit Log message for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

newValueStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for newValue. Note, that not all audit log entries will contain this field, it is primarily used for Audit Logs for updates to existing objects.

numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

oldValueStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for oldValue. Note, that not all audit log entries will contain this field, it is primarily used for Audit Logs for updates to existing objects.

orderByStringoptionalDefaults to insertInstant DESC

The database column to order the search results on plus the order direction.

The possible values are:

  • insertInstant - the instant when the Audit Log was created
  • insertUser - the user that created the Audit Log
  • message - the message of the Audit Log
  • tenant - the Tenant Name associated with the Audit Log (nullable) Available since 1.65.0

For example, to order the results by the insert instant in a descending order, the value would be provided as insertInstant DESC. The final string is optional and can be set to ASC or DESC.

reasonStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for reason. Note, that not all audit log entries will contain this field.

startLongoptional

The start instant of the date/time range to search within.

startRowIntegeroptionalDefaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

tenantIdUUIDoptionalAvailable since 1.65.0

Restricts the results to Audit Logs belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

userStringoptional

The string to search in the Audit Log user for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

API Key Authentication
Searches the Audit Logs using the given search criteria
POST/api/system/audit-log/search

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body#

search.endLongoptional

The end instant of the date/time range to search within.

search.messageStringoptional

The string to search in the Audit Log message for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

search.newValueStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for newValue. Note, that not all audit log entries will contain this field, it is primarily used for Audit Logs for updates to existing objects.

In versions >= 1.49.0 sensitive values may be masked.

search.numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

search.oldValueStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for oldValue. Note, that not all audit log entries will contain this field, it is primarily used for Audit Logs for updates to existing objects.

In versions >= 1.49.0 sensitive values may be masked.

search.orderByStringoptionalDefaults to insertInstant DESC

The database column to order the search results on plus the order direction.

The possible values are:

  • insertInstant - the instant when the Audit Log was created
  • insertUser - the user that created the Audit Log
  • message - the message of the Audit Log
  • tenant - the Tenant Id associated with the Audit Log (nullable) Available since 1.65.0

For example, to order the results by the insert instant in a descending order, the value would be provided as insertInstant DESC. The final string is optional and can be set to ASC or DESC.

search.reasonStringoptionalAvailable since 1.30.0

The string to search for in the Audit Log field for reason. Note, that not all audit log entries will contain this field.

search.startLongoptional

The start instant of the date/time range to search within.

search.startRowIntegeroptionalDefaults to 0

The offset row to return results from. If the search has 200 records in it and this is 50, it starts with row 50.

search.tenantIdUUIDoptionalAvailable since 1.65.0

Restricts the results to Audit Logs belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

search.userStringoptional

The string to search in the Audit Log user for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

Response#

The response for this API contains the Audit Logs matching the search criteria in paginated format.

Response Codes
CodeDescription
200The request was successful. The response will contain a JSON body.
400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

auditLogsArray

The list of Audit Logs returned by the search.

auditLogs[x].dataObject

Additional details of an audit log.

auditLogs[x].data.newValueString

The new value of a changed object.

In versions >= 1.49.0 sensitive values may be masked.

auditLogs[x].data.oldValueString

The previous value of a changed object.

In versions >= 1.49.0 sensitive values may be masked.

auditLogs[x].data.reasonString

The reason why the audit log was created.

auditLogs[x].tenantIdUUIDAvailable since 1.65.0

The Id of the Tenant associated with this Audit Log. This field will be null for instance-scoped audit logs.

auditLogs[x].idLong

The Audit Log unique Id.

auditLogs[x].insertInstantLong

The instant when the Audit Log was created.

auditLogs[x].insertUserString

The user that created the Audit Log.

auditLogs[x].messageString

The message of the Audit Log.

totalInteger

The total number of Audit Logs matching the search criteria. Use this value along with the numberOfResults and startRow in the Search request to perform pagination.

Example JSON Response

{
  "auditLogs": [
    {
      "id": 1,
      "insertInstant": 1471786483322,
      "insertUser": "user@fusionauth.io",
      "message": "Audit Log 1"
    },
    {
      "id": 2,
      "insertInstant": 1471786489322,
      "insertUser": "user@fusionauth.io",
      "message": "Audit Log 2"
    },
    {
      "data": {
        "externalId": "_applicationA"
      },
      "newValue:": "{\"name\": \"bar\"}",
      "oldValue": "{\"name\": \"foo\"}",
      "reason": "Because I like to change things.",
      "id": 3,
      "insertInstant": 1471796483322,
      "insertUser": "user@fusionauth.io",
      "message": "Changed Application"
    }
  ],
  "total": 100
}

Export Audit Logs#

Available Since Version 1.7.0

This API is used to export the Audit Logs, the response will be a compressed zip archive.

Request#

API Key Authentication
Export the Audit Logs matching the criteria
GET/api/system/audit-log/export?message={message}&start={start}&end={end}&user={user}

When calling the API using a GET request you will send the export criteria on the URL using request parameters. In order to simplify the example URL above, not every possible parameter is shown, however using the provided pattern you may add any of the documented request parameters to the URL.

Request Parameters#

dateTimeSecondsFormatStringoptional

The format string used to format the date and time columns in the export result.

When this parameter is omitted a default format of M/d/yyyy hh:mm:ss a z will be used. See the DateTimeFormatter patterns for additional examples.

endLongoptional

The end instant of the date/time range to search within.

messageStringoptional

The string to search in the Audit Log message for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

startLongoptional

The start instant of the date/time range to search within.

tenantIdUUIDoptionalAvailable since 1.65.0

Restricts the results to Audit Logs belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

userStringoptional

The string to search in the Audit Log user for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

zoneIdStringoptional

The time zone used to adjust the stored UTC time in the export result.

For example:

America/Denver or US/Mountain

When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.

API Key Authentication
Export the Audit Logs matching the criteria
POST/api/system/audit-log/export

When calling the API using a POST request you will send the export criteria in a JSON request body.

Request Body#

criteria.endLongoptional

The end instant of the date/time range to include in the export.

criteria.messageStringoptional

The string to search in the Audit Log message for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

criteria.startLongoptional

The start instant of the date/time range to include in the export.

criteria.tenantIdUUIDoptionalAvailable since 1.65.0

Restricts the results to Audit Logs belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.

criteria.userStringoptional

The string to search in the Audit Log user for. This can contain wildcards using the asterisk character (*). If no wildcards are present, this parameter value will be interpreted as *value*.

dateTimeSecondsFormatStringoptional

The format string used to format the date and time columns in the export result.

When this parameter is omitted a default format of M/d/yyyy hh:mm:ss a z will be used. See the DateTimeFormatter patterns for additional examples.

zoneIdStringoptional

The time zone used to adjust the stored UTC time in the export result.

For example:

America/Denver or US/Mountain

When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.

Response#

The response for this API will contain a compressed zip of the audit logs.

Response Codes
CodeDescription
200

The request was successful. The response will be a compressed archive byte stream with a Content-Type of application/zip.

400The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404The object you requested doesn't exist. The response will be empty.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.