Skip to main content

Audit Log APIs

Beta feature

Audit Log API access is in beta and may be subject to change. Please contact us to provide feedback.

The Audit Log is a record of user actions within your organization. It records HTTP requests in the Workbench, to the Atomic API and from the Atomic SDKs. The Audit Log API can be used to retrieve these records.

A credential role of workbench is required to utilize the Audit Log API.

You can interact with the Audit Log API using Insomnia (follow the Insomnia instructions) or curl. When using curl, you'll need to set up your Authentication first.

Detailed specs and examples can be found in the Atomic API spec for the Audit Logs endpoint.

Audit Logs API​

Retrieve recent Audit Logs. Note that these logs are written from a queue-based system so at times of high load on the system may be delayed. Only the last 7 days of Audit Logs are available to query from this endpoint. To retrieve data older than 7 days use the batched endpoint.

Retrieving audit log entries​

Retrieve log entries that match query string:

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/audit-log" \
    --header "Authorization: Bearer $TOKEN"

You should see a response similar to the the following:

{
  "data": [
    {
      "url": "/v1/{environmentId}/action-flow/{actionFlowId}/start",
      "status": 200,
      "auth": {
        "type": "clientCredentials", // client (sdk) |  workbench | signedPayload (API when using connectors) | clientCredentials (API)
        "clientId": "..."
      },
      "ip": "{ipAddress}", // IP address of the request origin
      "userAgent": "{userAgent}", // user agent of the request origin
      "method": "POST",
      "query": {}, // any query headers, can contain sensitive information
      "payload": "{\"flows\":[{\"target\":{\"type\":\"user\",\"targetUserIds\":[\"{userId}\"]}}]}", // request payload, can contain sensitive information
      "source": "customer-api", // workbench-api (workbench) | client-api (SDK) | customer-api (API)
      "organisationId": "{organisationId}",
      "environmentId": "{actionFlowId}",
      "time": 20.38384999334812, // duration of the request in ms
      "resource": {
        "type": "action_flow"
      },
      "action": {
        "type": "create",
        "description": "Start an action flow"
      },
      "created": "2023-06-15T22:51:31.687Z" // UTC time of the request completion
    }
  ],
  "cursor": "..." // Used for pagination
}

Filtering​

It is possible to filter by the authentication type of the event that generated the log entry. The authentication data can be found in the auth attribute of the log entry:

{
  "data": [
    {
      "id": "2021-01-28 00:19:50.326617+00-5142ad0978e5ed8b0bf9bf5b0d5fa649",
      "data": {
        ...
        "auth": {
          "type": "workbench", // this is the authentication type property
          "sub": "...",
          "appClientId": "...",
          "accountId": "..."
        },
        ...
      },
      "created": "2021-01-28T00:19:50.326Z"
    }
  ]
}

The filter is applied using an authType query parameter. For example to retrieve log entries for events that used the workbench authentication type:

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/audit-log?authType=workbench" \
    --header "Authorization: Bearer $TOKEN"

Accepted authentication types are:

  • client: SDK
  • clientCredentials: API
  • signedPayload: API when using connector triggers
  • workbench: Workbench

Pagination and limits​

By default, the first 100 log entries are returned. You can choose to return a different amount by using the limit query parameter i.e. limit=100. The maximum limit value is 1000.

When you make a request to get Audit Logs a cursor property is returned. To get the next page of results, use the cursor query parameter with the value returned from your last request to get the next page i.e. cursor={cursor from previous request}.

Only the last 7 days of Audit Logs are available to query from this endpoint. If a request includes a cursor referencing logs older than 7 days, an error will be returned.

Audit Logs Batched API​

Retrieve links to download batches of Audit Logs in newline-delimited JSON files. The links returned from this endpoint are valid for up to 5 minutes.

Retrieving batches​

This endpoint accepts two dynamic arguments in the URL path:

  • date: the hour-scoped time in which to retrieve entries for
  • source: one of "sdk", "api", or "workbench". Source determines the system which the Audit Logs are relevant to.

Retrieve batches in the hour of 2025-02-16T21:00:00 for Audit Log entries pertaining to requests from the Atomic SDKs:

curl -X GET "https://$ORG_ID.customer-api.atomic.io/v1/$ENVIRONMENT_ID/audit-log/batched/2025-02-16T21:00:00/sdk" \
    --header "Authorization: Bearer $TOKEN"

You should see a response similar to the the following:

{
  "data": {
    "links": [...],
    "date": "2025-02-16T21:00:00" // Formatted to the hour version of the date provided in the path, indicates the hour partition for which the links are relevant to
  }
}

Pagination and limits​

Only the first 1,000 files will be returned. Outside cases of extreme system use, this limit is more than sufficient for files batched within an hour's period.

To paginate this endpoint iterate the provided date by adding or subtracting an hour.

Last updated on