Tracking user access to Textual

Required global permissions:

  • Manage users and user groups

  • View all datasets

  • View all pipelines

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:

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, View All Pipelines

Query parameters
offsetinteger · int32Optional
limitinteger · int32Optional
outcomeall ofOptional
string · enumOptional

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

Possible values:
created_beforestring · date-timeOptional
created_afterstring · date-timeOptional
include_unidentified_eventsbooleanOptional
Responses
200

OK

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

OK

{
  "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
    }
  ]
}

Last updated

Was this helpful?