Access Audit Logs via API

All teams have an Audit log accessible from the Admin Team Center, or via API.

Our Audit logs API was built for teams who have additional security, legal, or compliance requirements. With the API, you can:

  • Send data to a security information and event management (SIEM) tool.
  • Watch for potential security issues or malicious attempts to access your team.
  • Use the API to build custom apps for better insight into how your company uses Catalytic.
note
  • Note: Audit logs show data dating back to mid-September 2021, when this feature and API method became available to teams.

How to use the Audit Logs API

To use the API, you’ll need to use the audit log endpoint and authenticate with an access token.

GET https://[$team].pushbot.com/v1/[$team]/audit-logs

By default, the API returns a content-type of application/json and uses pagination. You can also return the response as text/csv. The API supports filtering, excluding and sorting.

Authenticating with the API

Once you generate a token, use it as the content of an Authorization header, for example:

Authorization: Bearer d47ce248488acd8e8da8c98938ad8e9c81091838acea028d0e8f0b0a083717a

Any team admin can view and use the Audit logs API and access token. You can also regenerate the token at any time.

  1. Navigate to the Audit logs section of the Admin Team Center. > Admin > Audit Logs
  2. Select the API Access option in the page menu.

    screen readers look here
  3. Use to generate an access token. This token will only allow access into Catalytic audit log data for this team, and does not allow access into any other Catalytic APIs or data.

Using query parameters to filter, exclude, and sort

You can attach query parameters to the request to filter the data. To use query parameters, append the parameter onto your audit log endpoint. For example, to filter audit log events by a userID, you could use:

GET https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08

As another example, to filter by action type, just append ?action= followed by the parameter value below to the audit log endpoint:

GET https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Action%20status%20changed

Or for multiple filters:

GET https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Action%20status%20changed&action=Group%20activated

There are 7 types of filters you can use. The filters can be combined together, except in specific cases like userID and excludedUserID. Each filter has example configurations you can use as templates for your own API work.

startTime

The minimum date to filter events by, expressed in Unix time.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503 Return all events after September 6th
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&endTime=1631083982 Return all events after September 6th, and before September 8th
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&action=Table%20created Return all events after September 8th, with the action type “Table created”

There are many ways to get a time in Unix time, like using .valueOf() method in javascript. You can also use tools online to find a Unix time like https://www.unixtimestamp.com/.

endTime

The maximum date to filter events by, expressed in Unix time.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?endTime=1631083982 Return all events before September 8th
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&endTime=1631083982 Return all events after September 6th, and before September 8th
https://[$team].pushbot.com/v1/[$team]/audit-logs?endTime=1631083982&action=Group%20deactivated Return all events before September 8th, with the action type “Group deactivated”

There are many ways to get a time in Unix time, like using .valueOf() method in javascript. You can also use tools online to find a Unix time like https://www.unixtimestamp.com/.

userID

The userID or userIDs to filter audit log events by. Use this parameter to filter for a userID. This cannot be used in conjunction with the excludedUserID parameter.

To find a user’s ID, use the users application table in the user ID column, or from the user’s profile page by checking the page URL.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08 Return all events with the userID
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08&userID=24552c0528505e55f5b5a08&userID=33bac4b5a5cba5c4b4c5a4d Return all events with any of the 3 user ID’s
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&userID=24552c0528505e55f5b5a08 Return all events after September 6th with the following userID

excludedUserID

The userID or userIDs to exclude from the results. Use this parameter to filter for everything but the userID. This cannot be used in conjunction with the userID parameter.

To find a user’s ID, use the users application table in the user ID column, or from the user’s profile page by checking the page URL.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedUserID=1091838acea028d0e8f0b0a08 Return all events without the following userID
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedUserID=1091838acea028d0e8f0b0a08&excludedUserID=24552c0528505e55f5b5a08&excludedUserID=33bac4b5a5cba5c4b4c5a4d Return all events without any of the 3 user ID’s
https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630997503&excludedUserId=24552c0528505e55f5b5a08 Return all events after September 6th without the following userID

action

The action or actions to filter audit log events by. Use this parameter to filter for an action. This cannot be used in conjunction with the excludedAction parameter.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated Return all events associated with a specific action type
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&action=Table%20created Return all events associated with either of two action types
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&userID=1091838acea028d0e8f0b0a08 Return all events associated with a specific userID and action type

For a list of all the action and parameter values, see the following list of Audit log actions and descriptions.

Audit log actions and descriptions

To filter by an action, first find it in the left hand column. Then, take the formatted parameter value in the right column to use in your query.

Action Parameter Value
Action status changed Action%20status%20changed
File uploaded File%20uploaded
Group created Group%20created
Group activated Group%20activated
Group deactivated Group%20deactivated
Group role changed Group%20role%20changed
User added to group User%20added%20to%20group
User removed from group User%20removed%20from%20group
Integration connection created Integration%20connection%20created
Integration connection removed Integration%20connection%20removed
Integration permissions changed Integration%20permissions%20changed
Table archived Table%20archived
Table column added Table%20column%20added
Table column removed Table%20column%20removed
Table created Table%20created
Table edited Table%20edited
Table permissions changed Table%20permissions%20changed
Table unarchived Table%20unarchived
Web form task completed Web%20form%20task%20completed
Task completed Task%20completed
Task reassigned Task%20reassigned
Team setting changed Team%20setting%20changed
Team SSO disabled Team%20SSO%20disabled
Team SSO enabled Team%20SSO%20enabled
User accepted invite User%20accepted%20invite
User activated User%20activated
User changed password User%20changed%20password
User deactivated User%20deactivated
User entered incorrect password User%20entered%20incorrect%20password
User attempted login when locked out User%20attempted%20login%20when%20locked%20out
User locked out User%20locked%20out
User logged in User%20logged%20in
User logged out User%20logged%20out
User profile changed User%20profile%20changed
User role changed User%20role%20changed
User sent invite User%20sent%20invite
Workflow archived Workflow%20archived
Workflow cancelled Workflow%20cancelled
Workflow commented on Workflow%20commented%20on
Workflow created Workflow%20created
Workflow draft created Workflow%20draft%20created
Workflow draft publish request cancellation Workflow%20draft%20publish%20request%20cancellation
Workflow draft publish request Workflow%20draft%20publish%20request
Workflow edited Workflow%20edited
Workflow exported Workflow%20exported
Workflow imported Workflow%20imported
Workflow instance edited Workflow%20instance%20edited
Workflow instance permissions changed Workflow%20instance%20permissions%20changed
Workflow permissions changed Workflow%20permissions%20changed
Workflow started Workflow%20started
Workflow trigger created Workflow%20trigger%20created
Workflow trigger edited Workflow%20trigger%20edited
Workflow trigger removed Workflow%20trigger%20removed
Workflow unarchived Workflow%20unarchived
Workspace created Workspace%20created
Workspace removed Workspace%20removed
Workflow added to workspace Workflow%20added%20to%20workspace
Workflow removed from workspace Workflow%20removed%20from%20workspace
Workspace added to another workspace Workspace%20added%20to%20another%20workspace
Workspace removed from another workspace Workspace%20removed%20from%20another%20workspace

excludedAction

The action or actions to exclude from the results. Use this parameter to filter for every action but the action specified. This cannot be used in conjunction with the action parameter.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated Return all events except those with a specific action type.
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated&excludedAction=Table%20created Return all events except those associated with either of two action types.
https://[$team].pushbot.com/v1/[$team]/audit-logs?excludedAction=Group%20deactivated&userID=1091838acea028d0e8f0b0a08 Return all events associated with a specific userID, that aren’t associated with a specific action type

For a list of all the action and parameter values, see the following list of Audit log actions and descriptions.

Audit log actions and descriptions

To filter by an action, first find it in the left hand column. Then, take the formatted parameter value in the right column to use in your query.

Action Parameter Value
Action status changed Action%20status%20changed
File uploaded File%20uploaded
Group created Group%20created
Group activated Group%20activated
Group deactivated Group%20deactivated
Group role changed Group%20role%20changed
User added to group User%20added%20to%20group
User removed from group User%20removed%20from%20group
Integration connection created Integration%20connection%20created
Integration connection removed Integration%20connection%20removed
Integration permissions changed Integration%20permissions%20changed
Table archived Table%20archived
Table column added Table%20column%20added
Table column removed Table%20column%20removed
Table created Table%20created
Table edited Table%20edited
Table permissions changed Table%20permissions%20changed
Table unarchived Table%20unarchived
Web form task completed Web%20form%20task%20completed
Task completed Task%20completed
Task reassigned Task%20reassigned
Team setting changed Team%20setting%20changed
Team SSO disabled Team%20SSO%20disabled
Team SSO enabled Team%20SSO%20enabled
User accepted invite User%20accepted%20invite
User activated User%20activated
User changed password User%20changed%20password
User deactivated User%20deactivated
User entered incorrect password User%20entered%20incorrect%20password
User attempted login when locked out User%20attempted%20login%20when%20locked%20out
User locked out User%20locked%20out
User logged in User%20logged%20in
User logged out User%20logged%20out
User profile changed User%20profile%20changed
User role changed User%20role%20changed
User sent invite User%20sent%20invite
Workflow archived Workflow%20archived
Workflow cancelled Workflow%20cancelled
Workflow commented on Workflow%20commented%20on
Workflow created Workflow%20created
Workflow draft created Workflow%20draft%20created
Workflow draft publish request cancellation Workflow%20draft%20publish%20request%20cancellation
Workflow draft publish request Workflow%20draft%20publish%20request
Workflow edited Workflow%20edited
Workflow exported Workflow%20exported
Workflow imported Workflow%20imported
Workflow instance edited Workflow%20instance%20edited
Workflow instance permissions changed Workflow%20instance%20permissions%20changed
Workflow permissions changed Workflow%20permissions%20changed
Workflow started Workflow%20started
Workflow trigger created Workflow%20trigger%20created
Workflow trigger edited Workflow%20trigger%20edited
Workflow trigger removed Workflow%20trigger%20removed
Workflow unarchived Workflow%20unarchived
Workspace created Workspace%20created
Workspace removed Workspace%20removed
Workflow added to workspace Workflow%20added%20to%20workspace
Workflow removed from workspace Workflow%20removed%20from%20workspace
Workspace added to another workspace Workspace%20added%20to%20another%20workspace
Workspace removed from another workspace Workspace%20removed%20from%20another%20workspace

orderBy

How to order results by. At this time, the Audit logs api supports ordering by the createdAt field, in either ascending or descending order.

Example Description
https://[$team].pushbot.com/v1/[$team]/audit-logs?orderBy=createdAt%20DESC Return events, and order by createdAt in descending order.
https://[$team].pushbot.com/v1/[$team]/audit-logs?action=Group%20deactivated&orderBy=createdAt%20ASC Return all events associated with a specific action type, and order by createdAt field in ascending order
https://[$team].pushbot.com/v1/[$team]/audit-logs?userID=1091838acea028d0e8f0b0a08&orderBy=createdAt%20DESC Return all events associated with a specific userID and order by createdAt in descending order

More information on exporting and response formats$$

By default, the API returns the content-type of application/json and uses pagination. To make the response easier to import into your system, pagination can be disabled by constraining the timespan (startTime and endTime parameters), to a maximum of 24 hours. If done correctly, all matching events are returned in a single response.

For example, the following parameter returns results in a 12 hour window between 8AM and 8PM on September 6th.

https://[$team].pushbot.com/v1/[$team]/audit-logs?startTime=1630940400&endTime=1630983600

Additionally, you can output the response as a csv by adding the header Accept: text/csv. If a CSV response is used, be sure to use the startTime and endTime parameters, as the maximum timespan of 24 hours is enforced since pagination is not supported with CSV.

Response fields

The response body of an Audit log export uses a defined set of fields:

  • When the response is in the default JSON format, the response is an object with a single auditLogs field. The field is an array whose contents will be individual JSON objects for each audit log event.
  • When using the CSV response format, each header is a field, and each row is a single audit log event.
Response Fields Description
auditLogID Required. An internal identifier used to uniquely identify each audit log event.
teamName Required. The teamName being queried.
userID Required. The userID of the user initiating the event being logged. In most cases, the initiator detail is of minor consequence. For example, starting or cancelling a workflow, making a change to a team setting all only have one user involved.

However, some events must keep the initiator in mind for accuracy, such as inviting a user to your team (the initiator is the person sending the invite), accepting an invite from your team (the initiator is the person receiving the invite and making a new account), and user permissions changes (the initiator is the person making the changes, not the person or persons being given access to a resource).

If the client initiating the event is a guest user, and is not logged in to the Catalytic platform, the userID will be “10000000-0000-0000-0000-000000000000”.
email The email of the user initiating the event being logged.

If the client initiating the event is a guest user, and is not logged in to the Catalytic platform, the email will be “Guest”.
clientIP The IP of the user initiating the event being logged at the time the event was logged.
action Required. The action the event is executing.
category Required. The category of the action the event is executing. Each action is contained by a single category. Categories are used for organization. You can see a list of categories on the View audit logs for your teams page.
resourceIDs Required. A series of identifiers used to link to the resource being changed. From this data, a link to the resource that was changed can be constructed for further review, as long as that resource has not been deleted.
resourceDisplayName A readable name that is used to easily identify the resource referenced by the resourceIDs. This should only be used for display purposes, and will not uniquely identify a resource.
details Extra context on the changes that were made. This will only be provided for certain actions, and only in certain scenarios. For example, when making permissions changes to a resource, the users added and/or removed will be recorded here.
createdAt Required. The UTC date and time of the event in ISO-8601 format.

Example cURL requests

Below are some example requests in cURL format , assuming:

  • a teamName of teamname
  • a time span between a startDate of midnight 2021-08-04 UTC (1630728000000) and an endDate of midnight 2021-08-05 UTC (1630814400000)
  • an audit log API access token of d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77
One User in CSV Format
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &userID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc" \
--header 'Accept: text/csv' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
All But Two Users In CSV
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\
&endTime=1630814400000\ &excludedUserID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc\ &excludedUserID=3ca5b643-8cac-4b1a-80c9-eafa6d9e1f73" \
--header 'Accept: text/csv' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
Only Failed Login Attempts In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\ ?startTime=1630728000000\
&endTime=1630814400000\ &action=User%20entered%20incorrect%20password" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
Reverse Ordering In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &orderBy=createdAt%20ASC" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'
One User’s Workflow Instance Cancellations In JSON
curl \
--request GET \
--url "https://teamname.pushbot.com/v1/teams/teamname/audit-logs\
?startTime=1630728000000\ &endTime=1630814400000\ &userID=f8968f91-ccd7-41fb-a5f1-178f1b96eedc\ &action=Workflow%20cancelled" \
--header 'Accept: application/json' \
--header 'Authorization: Bearer d47ce24726b8d74105b3e64a4cdbe6c8ecd4e5cfb2969a9809099962d6cb7b77'

Example response

Below is an example response with a content type of application/json ordered from youngest to oldest.

Example JSON response
{
"auditLogs": [
{
"auditLogID": "445a8c38-70a1-4673-84d9-52f4712d4cce", "teamName": "catalytic",
"userID": "10000000-0000-0000-0000-000000000000", "email": "Guest",
"clientIP": "54.55.56.57",
"action": "Task webform completed",
"category": "Task",
"resourceIDs":
"Instance:e145c281-3e87-4ea8-9f8a-d0860f971712:Task:936bfbc8-9cab-422c-88c4 -7aee30b4d207",
"resourceDisplayName": "Webform", "details": null,
"createdAt": "2021-08-17T18:10:03.671Z"
}, {
"auditLogID": "abdb60da-942b-4f72-a316-ace85ed648da", "teamName": "catalytic",
"userID": "10000000-0000-0000-0000-000000000000", "email": "Guest",
"clientIP": "54.55.56.57", "action": "Workflow started", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Instance:e145c281-3e87-4ea8- 9f8a-d0860f971712",
"resourceDisplayName": "Webform",
"details": "Started workflow from trigger Webform", "createdAt": "2021-08-17T18:09:22.586Z"
}, {
"auditLogID": "d4c367d2-b84d-4299-93b8-a0069621d5a9", "teamName": "catalytic",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115",
"action": "Workflow edited",
"category": "Workflow",
"resourceIDs": "Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723", "resourceDisplayName": "Test Workflow",
"details": "Edited ordering and dependencies of workflow steps",
"createdAt": "2021-08-17T18:08:56.632Z" },
{
"auditLogID": "c33ec6b7-9d95-46a5-929a-7938d935a85f", "teamName": "catalytic",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115",
"action": "Workflow edited",
"category": "Workflow",
"resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Step:email-task", "resourceDisplayName": "Email Task",
"details": "Edited step Email Task",
"createdAt": "2021-08-17T18:08:55.780Z"
}, {
"auditLogID": "1dc3934e-1370-45cd-869d-e9de5e67a0e8", "teamName": "catalytic",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115", "action": "Workflow trigger removed", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Webhook:0840c8d3ea91ca1aa216 1c799f92d1aa3d97c910fc29ea7869e11871ccb46802",
"resourceDisplayName": "Test Scheduled Trigger", "details": "Removed Scheduled trigger", "createdAt": "2021-08-17T18:07:28.672Z"
}, {
"auditLogID": "17c30942-cea3-40f3-96cb-9f078f6890ee", "teamName": "catalytic",
"userID": "10a379c3-15c5-4638-897e-fa97d76b4f1d", "email": "testuser@testdomain.com",
"clientIP": "112.113.114.115", "action": "Workflow cancelled", "category": "Workflow", "resourceIDs":
"Workflow:15527b4c-bef5-4d7e-a4fc-aee55dc4e723:Instance:95e59e4f-e642-4b6a- a4fd-373c9252bae3",
"resourceDisplayName": "Webform",
"details": null,
"createdAt": "2021-08-17T18:07:19.328Z" },
], "nextPageToken": ""
}

Get help with a problem or question

If something’s not working as expected, or you’re looking for suggestions, check through the options below.

How do I find a userID?

To find a user’s ID, use the users application table in the user ID column, or from the user’s profile page by checking the page URL.

screen readers look here
The string at the end of the URL is the user's ID.

Sorry about that. What was the most unhelpful part?









Thanks for your feedback

We update the Help Center daily, so expect changes soon.

Link Copied

Paste this URL anywhere to link straight to the section.

Need more help?

If you're signed in to Catalytic Community, you can ask other users a question. You'll be redirected to Community where you can add more info.