Introduction

Getting started

Walkthrough Guides

CafeX Apps

Workflows

Using CafeX Collaborate App

Reporting

Managing CafeX

Integrating CafeX

Security

Reporting

Accessing Audit Information Programmatically

Modified on Fri, 09 Jun 2023 at 03:02 AM

CafeX Audit Events API

Introduction

The CafeX Audit Events API allows the retrieval of audit event data for CafeX tenants. Data can be filtered by time and other event properties. Data access is secured using an authorization token which can be generated by CafeX tenants.


Endpoint

The API can be accessed on


https://app.cafex.com/audit-search-rest/search


Authentication

Access to the API is authenticated by including an authorization token in the header of the request.


To generate this token a Client application must be created inside CafeX.


To do this log in to CafeX as a tenant administrator:


  • Click on the three dot header menu and select “Tenant settings”


  • Under “Management” click on “Client applications”

 

  • Click on “Add” and give the client application a name (such as “Audit Events API client application”


  • A client application will be created with a Client ID and a Client secret.



Once a Client ID and Client secret exists a HTTP request needs to be made to generate an authorization token.


POST https://auth.cafex.com/authserver/token


Include a x-www-form-urlencoded request body that contains the following parameters: (replace the client_id and client_secret with the ones previously generated)


grant_type : client_credentials
client_id: {CLIENT ID HERE}
client_secret: {CLIENT SECRET HERE}


This should contain a response with an access_token field.


Take this access_token part and include it in an “Authorization” header on the search HTTP request in the format:


Bearer {ACCESS TOKEN HERE}


This token lasts eight hours from generation before a new one needs to be generated (the same Client ID and Client secret can be used).


Date/time format

Date and time are accepted in the ISO 8601 UTC format. e.g.


2023-01-30T12:00:00.000
2023-01-30T12:00:00
2023-01-30T12:00
2023-01-30


If no offset is provided then UTC is used. A timezone offset can be provided e.g.


2023-01-30T12:00:00-05:00


All dates/times returned are in the full format as UTC (no offset). e.g.


2023-01-30T12:00:00.000+00:00


Search

Searching can be performed by sending a HTTP request to:


POST https://app.cafex.com/audit-search-rest/search


Your request requires an Authorization header (see: Authentication).

Your request requires a JSON encoded body to be present which contains some required and optional attributes.


For best performance, queries should be as specific as possible. (small date ranges and specifying event types and services, for example).


Important: Events are stored for a maximum of one year, so any events which happened more than a year ago will not be available.


Request Body


Attribute name

Type

Required

Description

page

object

true

An object containing a pageSize integer value and an optional continuationToken string value. 

pageSize cannot be larger than 100.

continuationToken is passed back in responses where more results are available. This can be used here to retrieve the next set of results.

timestampFrom

string

true

A date in the format described above

timestampTo

string

true

A date in the format described above

service

string array

false

An array of strings that contain service names to filter on. See “Service values” below for a list of accepted values.

type

string array

false

An array of strings that contain type names to filter on. See “Type values” below for a list of accepted values.

action

string array

false

An array of strings that contain action names to filter on. See “Action values” below for a list of accepted values.

message

string

false

Part of or a complete message to match.

miniAppId

string

false

The ID of an app to match.

trackId

string

false

The ID of a workspace to match.

conferenceSessionId

string

false

The ID of a conference session to match.

userId

string

false

The ID of a user to match. See “Finding userId for searching” below for how to find a user’s userId value.

changes

object

false

An object containing an attribute name and value which will match events that log changes. Example in “Example Request Body” below.

secondaryAttributes

object

false

An object containing a secondary attribute name and value to filter on. Example in “Example Request Body” below.

sortDirection

string

false

A string ASC or DESC which will sort the results by timestamp ascending or descending. If this is not specified a default of descending is used.



Example Request Body

{
   "page": {
       "pageSize": 100,
       "continuationToken": “abcdefghijklmnopqrstuvwxyz…”
   },
   "timestampFrom": "2023-01-01T09:00.00",
   "timestampTo": "2023-01-07T17:00.00",
   "service": ["TRACK", "ENTRY"],
   "secondaryAttributes": {
      "objectId": "23804d37-d753-4dad-84bb-8f691a50aa12"
   },
   "changes": {
      "status": "ACTIVE",
      "type": "STANDARD"
   },
   "sortDirection": "ASC"
}


Response Body


Attribute name

Type

Always present

Description

page

object

true

An object containing a pageSize integer value and an optional continuationToken, string value.


The continuation token can be used in a subsequent request to get the next set of results for the query (see the search section above).


If no continuationToken is present it means that no more results exist after the current set of results.

events

array

true

An array of event objects (see below)



Response Body event object


Attribute name

Type

Always present

Description

id

string

true

An ID which identifies the event.

service

string

true

The service which recorded the event. e.g. CUSTOM_VIEW

type

string

true

The type of event. e.g ENTRY_CREATE

action

string

true

The action of the event. e.g. SUCCESS

timestamp

string

true

A date in the format described above

message

string

false

The message describing the event.

trackId

string

false

The ID of the track which the event happened on.

userEmail

string

false

The email address of the user that the event happened against.

userId

string

false

The ID of the user that the event happened against.

userAccountId

string

false

The ID of the account which the user belongs to.

ipAddress

string

false

The IP address that the event happened against.

secondaryAttributes

object

false

An object containing string key/ string value pairs of extra attributes which relate to the event.

changes

object

false

An object containing string key/object value pairs of attributes describing changes which the events caused. The object which relates to the attribute name contains an optional before and after value which contains the attribute value before/after the change.


Example Response Body


{
    "page": {
        "pageSize": 100,
        "continuationToken": “abcdefghijklmnopqrstuvwxyz…”,
    },
    "events": [
        {
            "id": "61580af7-6def-4743-877f-3724fc83fc31",
            "service": "ENTRY",
            "type": "ENTRY_ACCESS",
            "action": "SUCCESS",
            "timestamp": "2022-01-01T09:00:00.123+00:00",
            "message": "Entry accessed: example.jpeg, filename type: jpeg",
            "trackId": "849c1214-fa97-4639-ade0-2219d3627823",
            "secondaryAttributes": {
                "objectId": "6e94b5a5-6753-4e4a-b57f-4ce220068a73",
            },
            "userEmail": "someone@somewhere.com",
            "userId": "910522e7-7664-4a81-98ca-16c1b725e14e",
            "userAccountId": "a6cc2b41-e251-44ce-9efa-a46d41dbe0cd",
            "ipAddress": "123.456.78.901"
        },
        ...
    ]
}


Finding userId for searching

In the search request a userId value can be passed to filter by the user who carried out the action. In order to find a userId you can do the following:


  • Log in to CafeX as a tenant administrator and click on the three dot header menu and select “Tenant settings”


  • Under “Management” click on “Users”

  • Find the user you would like to filter on and copy their ID from the correct row. You can use this as the userId value in a search request.


Reference

Service values

ACTION
API
ARTICLE
AUTH
CUSTOM_VIEW
DASHBOARD
ENTRY
PARTNER
RULES_ENGINE
SYSTEM
TENANT
TRACK
USER
USER_GROUP


Type values

API_KEY_CREATED
API_KEY_DELETED
AUDIT_QUERY
AUTH_LOGIN
AUTH_LOGOUT
CUSTOM_VIEW_EXIT_VIEW
CUSTOM_VIEW_INVOKE_ACTION
CUSTOM_VIEW_LOADED
CUSTOM_VIEW_LOGOUT
CUSTOM_VIEW_UI_ACTION
CUSTOM_VIEW_UI_CONTEXT_SWITCH
CUSTOM_VIEW_UI_INFO
DASHBOARD_ADD
DASHBOARD_DELETE
DASHBOARD_UPDATE
DATA_SOURCE_CREATED
DATA_SOURCE_DELETED
DATA_SOURCE_RECORDS_CREATE
DATA_SOURCE_RECORDS_DELETE
DATA_SOURCE_RECORDS_RETRIEVE
DATA_SOURCE_RECORDS_UPDATE
DATA_SOURCE_UPDATED
EMAIL_RULE_CHANGED
EMAIL_RULE_CREATED
EMAIL_RULE_DELETED
ENTRY_ACCESS
ENTRY_ACTION_ADD
ENTRY_ACTION_DELETE
ENTRY_ACTION_UPDATE
ENTRY_APPROVAL_REQUEST_ADD
ENTRY_APPROVAL_REQUEST_APPROVE
ENTRY_APPROVAL_REQUEST_DELETE
ENTRY_APPROVAL_REQUEST_UPDATE
ENTRY_CREATE
ENTRY_DELETE
ENTRY_FILE_DELETE
ENTRY_FILE_DOWNLOAD
ENTRY_FILE_SCAN
ENTRY_FILE_UPDATE
ENTRY_TEXT_FILE_DELETE
ENTRY_TEXT_FILE_UPDATE
ENTRY_TRANSCRIPTION_REQUEST
ENTRY_UPDATE
ENTRY_VIEW
GOOGLE_FILE_DOWNLOAD
GOOGLE_FILE_UPLOAD
GOOGLE_FILE_VIEW
KB_WIKI_CREATION
MINI_APP_ADDED
MINI_APP_DELETED
MINI_APP_UPDATED
MINI_APP_VIEW_ADDED
MINI_APP_VIEW_DELETED
MINI_APP_VIEW_UPDATED
ONEDRIVE_FILE_UPLOAD
ONEDRIVE_FILE_VIEW
PARTNERSHIP_CHANGED
PARTNERSHIP_CREATED
PARTNERSHIP_DELETED
RULESET_CREATED
RULESET_DELETED
RULESET_EXECUTED
RULESET_EXPORTED
RULESET_IMPORTED
RULESET_UPDATED
SYSTEM_SETTING_ACCESS
SYSTEM_SETTINGS_CHANGED
TASK_ADDED
TASK_DELETED
TASK_TABLE_ADDED
TASK_TABLE_DELETED
TASK_TABLE_UPDATED
TASK_UPDATED
TENANT_ACCESS
TENANT_CREATED
TENANT_SETTINGS_CHANGED
TRACK_ACCESS
TRACK_AUTO_ARCHIVE
TRACK_CHANGED
TRACK_COPY
TRACK_CREATED
TRACK_CREATION_SERVICE
TRACK_DELETED
TRACK_JOIN
TRACK_MEMBER_ADD
TRACK_MEMBER_ADD_PENDING
TRACK_MEMBER_ADD_REJECTED
TRACK_MEMBER_DELETE
TRACK_MEMBER_PENDING_ACCEPT
TRACK_MEMBER_PENDING_REJECT
TRACK_MEMBER_UPDATE
TRACK_RESTORE
TRACK_TRANSFER
UI_FLOW_ADDED
UI_FLOW_DELETED
UI_FLOW_UPDATED
USER_ANNOUNCEMENT_CHANGED
USER_ANNOUNCEMENT_CREATED
USER_ANNOUNCEMENT_DELETED
USER_CREATED
USER_GROUP_CREATED
USER_GROUP_DELETED
USER_GROUP_UPDATED
USER_SETTINGS_CHANGED
USER_UPDATED
WEBHOOK_NOTIFICATION_SENT


Action values

FAIL
START
SUCCESS


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article