Audit Log API

The Audit Log API allows site admins to get audit log metadata and audit log results to track activity on the platform. See the Audit Logs Documentation for more details.

See Instabase API authorization and response conventions for authorization and error convention details.

For the Audit Log API, URL_BASE defines the base domain and API prefix of your Instabase instance.

  • For instabase.com, the URL_BASE is https://www.instabase.com/api/v1.

  • For an on-premises installation of Instabase, your URL_BASE will be different.

For all Audit Log API calls, add ?pretty=true to the end of the query URL to return the JSON response in a more human readable, indented format.

Audit log metadata

Method Syntax
GET URL_BASE/auditlogs

Description

Get a map of each audit log type with the associated metadata, such as a description of the audit log type by sending a GET to URL_BASE/auditlogs.

Request parameters

No request parameters.

Response schema

All keys are returned in the response by default, unless marked as optional.

Key Description Value
status Status indicating whether the API call succeeded. OK/ERROR
data Optional. An object containing Audit log metadata. Present only if status is OK.
data/log_types An object containing metadata for the different types of audit logs supported.
data/log_types/<type>/description A string describing the audit log type.

Examples

Request

Example (Python):

url = URL_BASE + '/auditlogs'

payload = {}
headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.get(url, headers=headers, data=payload)
resp_data = json.loads(response.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "data": {
    "log_types": {
      "login": {
        "description": "\n          Login operation audit logs are generated on login or logout attempts. These logs also include information about how the login attempt was authenticated.\n          "
      },
      "account": {
        "description": "\n          Account operation audit logs are generated on new account creation or account metadata modification.\n          "
      },
      ...
      "diff": {
        "description": "\n        Diff app operations are generated when diff is executed from review OCR or diff app front end\n        "
      }
    }
  }
}

Audit log query

Method Syntax
POST URL_BASE/auditlogs

Description

Query audit logs by sending a POST to URL_BASE/auditlogs.

The query results are a list of audit logs which contain information for tracking different types of user activities on the platform. All audit logs contain a certain amount of common information, such as the timestamp of the operation being logged and the user who initiated the operation. Logs typically indicate if the operation was successful, and if not, provide a message describing the failure.

Given below is additional, operation specific information that is accompanied with different types of audit logs.

Account operation (account)

Generated upon account creation or deactivation, granting or removing site admin access, or user account metadata modification.

ACL operation (acl)

Generated on access control modifications to repository file/folder paths. Includes information about access control modification, such as the repository name and owner, the specific resource being modified, the ACL type (for example, read or write), and the user principal associated with the change.

App access operation (app_access)

Generated for each user attempt to access an Instabase App. Includes information about the user performing the action, the repo they attempted to access, and whether the operation was successful or denied.

API operation (api)

Generated each time a public REST API call is made. Includes information about the API call including the host URL and path suffix, the query string, the request method, and authentication method.

Diff app operation (diff)

Generated each time the Diff API is executed, in Review OCR or in the Diff app. Includes the user that performed the action, the repo the action was performed in, the files that were diffed. If the operation produced an error message, the message is included in the message field.

Env (env)

Generated each time a site config is updated. These configs are found in the Admin app’s Configuration tab.

Flow app operation (flow)

Generated each time a flow is started or completed.

  • A Flow start log contains information about the Flow including job id, the type of Flow being run, Flow path, input and output directories, and more.

  • A Flow completion log contains information about the Flow including job id, the type of Flow that was run, the Flow path, the job state (cancelled, success, or failure), input and output directories, the number of files processed by the flow, the total number of files, the starting and ending timestamps in milliseconds, and the number of completed flows.

Flow correction operation

Generated when a flow result phrase is corrected.

Group operation (group)

Generated for create, delete, or update operations to Instabase groups.

Key operation (key)

Generated for operations specific to environments with client-side encryption enabled. Logs include:

  • Encryption.

  • Decryption.

  • Listing all keys provided by the KMS provider.

  • Syncing keys from the KMS provider.

  • Rotating the master key used for encryption.

  • Updating the KMS provider metadata.

  • Retrieving the KMS provider metadata.

Licensing operation

Generated for various licensing-related operations, including:

  • Setting up a new license.

  • Previewing a license.

  • Installing and uninstalling a license.

  • Retrieving a license.

  • Retrieving license usage.

  • Compacting license usage.

  • Assigning and unassigning a license.

  • Getting assignments.

  • Backing up license usage.

Login operation (login)

Generated on login or logout attempts. Includes information about how the login attempt was authenticated.

Marketplace operation

Generated for the following Marketplace operations:

  • Listing Marketplace apps.

  • Installing and uninstalling applications.

  • Publishing new applications.

Model service operation (model_service)

Generated during model-service usage, logging when models are run or loaded.

Model training operation (model_training)

Generated for model-training operations, specifically their start and end time.

Mount operation (mount)

Generated when a subspace’s mount point is created, deleted or renamed.

NLP platform operation (nlp)

Generated each time the NLP API is executed in Flow by using an API or within a UDF. Includes the user that performed the action, the repo the action was performed in, and information about the specific NLP usage. If the operation produced an error message, a descriptive message is included in the message field.

NLP step (nlp_step)

Generated each time the NLP pipeline step is executed in Flow by using an API or within a UDF. Includes the user that performed the action, the repo the action was performed in, and information about the specific NLP usage. If the operation produced an error message, a descriptive message is included in the message field.

OAuth2 token operation (oauth2)

Generated for changes to made to OAuth2 tokens.

  • Creation or deletion of OAuth2 applications

  • Creation, deletion or updates of OAuth2 tokens

  • Deletion of all OAuth2 applications for a user

Org operation (org)

Generated on creation, deletion, or membership modifications of Organizations.

Reader app operation (reader)

Generated whenever Reader runs OCR to extract text from a document.

Repo operation (repo)

Generated on operations that affect a repository, including:

  • Creation or deletion

  • Renaming

  • Ownership transfer

  • Visibility updates

  • Changes to collaborators

Site ACL operation (site)

Generated upon access control modifications to site-level ACLs. This includes the addition or removal of users or groups to various Site permissions (Admin > Site settings > Site permissions).

Request parameters

Parameters are required unless marked as optional. The body of the request must be a JSON object with one or more of the following fields:

Name Type Description Values
size integer Optional. The maximum number of results to return. Default: 10
start integer Optional. The zero-indexed result number to start on for pagination. Default: 0
log_type string Optional. The audit log type to restrict the query on. One of the audit log types, which can be obtained from the audit log metadata API. Default: all log types
email string Optional. The user email to restrict the query on. Default: all users
end_time string Optional. Unix timestamp in milliseconds, indicating the end of the time range to query. Default: Current time
start_time string Optional. Unix timestamp in milliseconds, indicating the start of the time range to query. Default: one month before end_time

Response schema

All keys are returned in the response by default, unless marked as optional.

Key Description Value
status Status indicating whether the API call succeeded. OK/ERROR
data Optional. An object containing audit log query results. Present only if status is OK
data/results A list of results for the audit log query.

Examples

Request

Example (Python):

Request 3 audit logs for user support-testing@instabase.com for log type api between 2022-07-27 15:00 UTC and 2022-07-27 17:00 UTC, starting from the 2nd result onwards.

url = URL_BASE + '/auditlogs'

payload = {
  'size': 3,
  'start': 1,
  'log_type': 'api',
  'email': 'support-testing@instabase.com',
  'end_time': '1658941200000',
  'start_time': '1658934000000'
}

headers = {
  'Authorization': f'Bearer {token}'
}

response = requests.post(url, headers=headers, json=payload)
resp_data = json.loads(response.content)

Response

The response body is a JSON object.

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "data": {
    "results": [
      {
        "timestamp_millis": "1658936624809",
        "email": "support-testing@instabase.com",
        "log_type": "API_OPERATION",
        "host_url": "https://dogfood.instabase.com/",
        "ib_auth_method": "cookie",
        "method": "GET",
        "path": "/api/v1/accounts/support-testing/profile",
        "query_string": ""
      },
      {
        "timestamp_millis": "1658936624790",
        "email": "support-testing@instabase.com",
        "log_type": "API_OPERATION",
        "host_url": "https://dogfood.instabase.com/",
        "ib_auth_method": "cookie",
        "method": "GET",
        "path": "/api/v1/marketplace/list",
        "query_string": "is_installed=true"
      },
      {
        "timestamp_millis": "1658936539853",
        "email": "support-testing@instabase.com",
        "log_type": "API_OPERATION",
        "host_url": "https://dogfood.instabase.com/",
        "ib_api_headers": [
          "{\"type\":\"file\",\"get_content\":true}"
        ],
        "ib_auth_method": "cookie",
        "method": "GET",
        "path": "/api/v1/drives/ib_eng/tests/fs/Test Drive/files/workspace-eric/flow-edit-uat/edit-steps.ibflow",
        "query_string": ""
      }
    ]
  }
}

If not successful:

HTTP STATUS CODE 200

# body
{
  "status": "ERROR",
  "msg": "Not a valid log type: invalid-log-type"
}