Tracking user access to Textual

Required global permissions:

• Manage users and user groups

• View all datasets

Textual provides a REST API endpoint to track the following events that are related to user access and permissions:

• User account is created

• User account is removed

• User logs into Textual

• User fails to log into Textual

• User attempts to perform an action that they do not have permission for

• A permission set is created, updated, or deleted

• Permissions are added or removed from a permission set

• A permission set is added to or removed from a user or user group

In the results, each event includes the following information:

• Description of the action

• The user who performed the action

• When the action occurred

To request the access and permission events, use the following endpoint:

Search audit events

get

By default, the most recent 100 results will be returned.

Adding filters to the request

For each filter to add, use the following format:

parameterName=value
        

Use & to separate multiple filter values:

parameter1Name=parameter1Value&parameter2Name=parameter2Value
        

Valid filter parameters

You can filter the included events based on the following parameters:

event_category - The general category of event. For example, to filter the results to only include events related to permission sets:

event_category=PermissionSet
        

You can provide multiple event category values. For example, to filter the results to include events related to both assigned permissions and permission sets:

event_category=PermissionSet&event_category=AssignedPermissions
        

event_type - The specific type of event. To get the available event types, refer to Solar.Core.Enums.AuditEvents.AuditEventType. For example, to filter the results to only include when a permission set was created:

event_type=PermissionSetCreated
        

You can provide multiple event type values. For example, to filter the results to include both when a permission set was created and when a permission set was updated:

event_type=PermissionSetCreated&event_type=PermissionSetUpdated
        

outcome - Whether the event was successful (Success) or failed (Fail). For example, to filter the results to only include successful events:

outcome=Success
        

created_before - Used to only include events that occurred before the specified timestamp.

The timestamp uses the ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssZ). For example, to filter the results to only include events that occurred before 6:30 PM UTC on August 1, 2023:

created_before=2023-08-01T18:30:00Z
        

created_after - Used to only include events that occurred after the specified timestamp.

The timestamp uses the ISO 8601 format (yyyy-MM-dd'T'HH:mm:ssZ). For example, to filter the results to only include events that occurred after 10:00 AM UTC on July 27, 2023:

created_after=2023-07-27T10:00:00Z
        

include_unidentified_events - For self-hosted instances, whether to include events that do not have an identified user. By default, is false. These events might be server-generated or might be related to an unauthenticated action. To include events that do not have an identified user:

include_unidentified_events=true
        

Sample requests:

First 100 results by most recent:

GET /api/audit-events/search
        

Returns the first 20 results for permission set events that were successful:

GET /api/audit-events/search?limit=20&event_category=PermissionSet&outcome=Success

Required Permissions

• Global: Manage Users And Groups, View All Datasets

Query parameters

offsetinteger · int32Optional

Number of records to skip for pagination

limitinteger · int32Optional

Maximum number of records to return

outcomestring · enumOptional

The status of the audit event. Some event types may only log Success or Fail events.

Possible values:

created_beforestring · date-timeOptional

Only include events before this timestamp (ISO 8601)

created_afterstring · date-timeOptional

Only include events after this timestamp (ISO 8601)

include_unidentified_eventsbooleanOptional

Include events without an identified user (self-hosted only)

Responses

200

OK

application/json

Paginated response wrapper containing a page of results along with pagination metadata.

offsetinteger · int32Optional

The offset from the first item in the results. For example, 20 indicates that this batch of results starts with the 21st result.

limitinteger · int32Optional

The number of items the request limited the search to. The number of returned items can be less than the limit if not enough items exist or match the filter criteria.

pageNumberinteger · int32Optional

The number for this page of the results, starting at 1.

totalPagesinteger · int32Optional

The total number of pages in the results.

totalRecordsinteger · int32Optional

The total number of records in the results.

absoluteTotalRecordsinteger · int32Optional

The absolute total number of records available (unfiltered). This represents the total count without any search or filter applied.

hasPreviousPagebooleanOptional

Whether there is a previous page of results.

hasNextPagebooleanOptional

Whether there is a next page of results.

400

Invalid filter parameters or unsupported query option

text/plainapplication/jsontext/json

get

/api/audit-events/search

HTTPcURLJavaScriptPython

GET /api/audit-events/search HTTP/1.1
Accept: */*

{
  "offset": 1,
  "limit": 1,
  "pageNumber": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "absoluteTotalRecords": 1,
  "hasPreviousPage": true,
  "hasNextPage": true,
  "records": [
    {
      "id": "text",
      "timestamp": {},
      "eventCategory": "PermissionSet",
      "eventType": "UserCreated",
      "outcome": "Fail",
      "user": "text",
      "message": "text",
      "metadata": null
    }
  ]
}