Skip to main content

Audit Log API

Beta feature

This feature is currently in beta. 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.

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}.

Last updated on