Cloudera Data Lineage API: UserEvents documentation for user audit trails

Learn how to use the Cloudera Data Lineage (formerly Octopai) UserEvents API to query user audit events, including login, password reset, and user-management actions recorded automatically by the UserAccount API.

An audit trail is a security-relevant chronological record that provides documentary evidence of the sequence of activities that have affected a specific operation, procedure, or event. In the context of this API, it records the sequence of user activities or events.

Audit trails are a crucial aspect of security and compliance for many organizations. They are used to detect security incidents, performance issues, and to aid in the recovery from incidents. Additionally, they support the investigation and forensic analysis of how an incident occurred.

The UserEvents functionality contributes to a user audit trail the following ways:

User authentication: The API logs events related to user authentication, such as successful and failed login attempts. This can help detect potential security risks, like repeated failed login attempts that might indicate a brute-force attack.
User activity: The API records various user activities like page loads. By tracking these events, administrators can establish a pattern of normal behavior per user, making it easier to identify anomalous actions that could signify a breach.
Timestamps: Every event logged by the API includes a timestamp. This allows administrators to reconstruct the sequence of events leading up to a particular incident, which is vital in forensic investigations.
Data source: The IP addresses from which events originate are also recorded. This can be used to identify suspicious activity from unfamiliar sources.

By extracting and analyzing data from the UserEvents API, organizations can maintain a comprehensive audit trail that helps uphold security, facilitate incident response, and ensure regulatory compliance.

Events are recorded automatically when users log in, reset passwords, or when an admin creates, updates, or deletes users through the UserAccount API.

You must be familiar with HTTP methods, specifically POST.
You must be able to use command-line tools like curl.
You must have valid Cloudera Data Lineage user credentials that are email and password. To query user events or perform user-management API calls, you must log in with an admin account.

User login

To authenticate a user, send a POST request to the following endpoint:

https://[***COMPANY NAME***].octopai.com/api/UserAccount/Login

Construct and send this request using curl.


      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/Login' \
      --header 'Content-Type: application/json' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data-raw '{
      "Username": "[***USERNAME***]",
      "Password": "[***PASSWORD***]"
      }'

Replace [***COMPANY NAME***], [***USERNAME***], and [***PASSWORD***] with your actual values.

Extract access token
After a successful login, the API returns a JSON response containing an accessToken, which you use for subsequent authenticated requests.
Successful response example:
```
      {
      "accessToken": "[***ACCESS TOKEN***]",
      "expiration": "2026-07-21T15:36:37Z",
      "userName": "admin@example.com",
      "isAdmin": true,
      "authLevel": "ADMIN"
      }
    
```
Extract the accessToken from this response for the next steps.
Query user events
To retrieve user events, send a POST request to the /api/UserAccount/UserEvents endpoint. You must authenticate as an admin.

Include these headers on every request:
- Authorization: Bearer [***ACCESS TOKEN***]
- Company-Host: [***COMPANY NAME***].octopai.com
Construct and send the request.
```
      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/UserEvents' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data '{
      "PageNumber": "1",
      "RowsInPage": "100",
      "FromDate": "2026-07-21",
      "ToDate": "2026-07-21"
      }'
    
```
The request body supports these fields:
- PageNumber: Page number (1-based).
- RowsInPage: Number of events per page.
- FromDate: Start of the date filter. Accepted formats include yyyy-MM-dd, dd-MM-yyyy, and optional HH:mm:ss.
- ToDate: End of the date filter. Uses the same formats as FromDate.
If you omit FromDate and ToDate, the API returns events for all dates, subject to pagination. Results are ordered by newest first.
Understand the response
The response from the /api/UserAccount/UserEvents endpoint is an array of objects, each representing a user event.
Successful response example:
```
[
      {
      "type": "DELETE USER SUCCESS",
      "userName": "user@customer.com",
      "source": "203.0.113.42",
      "time": "2026-07-21T12:23:15.047",
      "actor": "admin@customer.com",
      "previousAuthLevel": "ADMIN",
      "newAuthLevel": null
      },
      {
      "type": "ROLE CHANGE SUCCESS",
      "userName": "user@customer.com",
      "source": "203.0.113.42",
      "time": "2026-07-21T12:23:05.94",
      "actor": "admin@customer.com",
      "previousAuthLevel": "VIEWER",
      "newAuthLevel": "ADMIN"
      },
      {
      "type": "LOGIN SUCCESS",
      "userName": "user@customer.com",
      "source": "203.0.113.42",
      "time": "2026-07-21T12:20:10.707",
      "actor": null,
      "previousAuthLevel": null,
      "newAuthLevel": null
      },
      {
      "type": "NEW USER SUCCESS",
      "userName": "user@customer.com",
      "source": "203.0.113.42",
      "time": "2026-07-21T12:19:08.14",
      "actor": "admin@customer.com",
      "previousAuthLevel": null,
      "newAuthLevel": "VIEWER"
      }
      ]
    
```
Each event object contains these fields:
- type: Event type string (for example, LOGIN SUCCESS, NEW USER SUCCESS).
- userName: Email address of the affected user.
- source: Client IP address from which the event originated.
- time: Timestamp of when the event occurred.
- actor: Email of the admin or authenticated user who performed the action. This field is null when not applicable.
- previousAuthLevel: User authorization level before a role change or at deletion.
- newAuthLevel: User authorization level assigned on create or after a role change.
The API records audit events automatically for login, password reset, user create, user update, and user delete.

For login, password reset, and other non-user-management events, actor, previousAuthLevel, and newAuthLevel are null.

User-management actions produce these success event types:
- NEW USER SUCCESS: Recorded when an admin creates a user through POST /api/UserAccount/NewUser. Populates actor and newAuthLevel.
- DELETE USER SUCCESS: Recorded when an admin deletes a user through POST /api/UserAccount/DeleteUser. Populates actor and previousAuthLevel. Delete is a soft delete that sets USER_ACTIVE = NO. A second delete attempt for the same user returns an error and logs DELETE USER FAIL.
- ROLE CHANGE SUCCESS: Recorded only when USER_AUTH_LEVEL changes through POST /api/UserAccount/UpdateUser. Populates actor, previousAuthLevel, and newAuthLevel.
- UPDATE USER SUCCESS: Recorded for name or job title updates through POST /api/UserAccount/UpdateUser. Does not populate actor, previousAuthLevel, or newAuthLevel.

Generate user-management audit events

To produce user-management audit events, perform the corresponding UserAccount API calls with the same Authorization and Company-Host headers, then query /api/UserAccount/UserEvents to verify the audit trail.

Create a user:


      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/NewUser' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data '{
      "USER_NAME": "[***USER EMAIL***]",
      "USER_FIRST_NAME": "[***FIRST NAME***]",
      "USER_LAST_NAME": "[***LAST NAME***]",
      "USER_AUTH_LEVEL": "VIEWER",
      "USER_PERMISSIONS": "lineage",
      "JOB_TITLE": "[***JOB TITLE***]"
      }'

Update a user profile (name only):


      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/UpdateUser' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data '{
      "USER_ID": "[***USER ID***]",
      "USER_NAME": "[***USER EMAIL***]",
      "USER_FIRST_NAME": "[***UPDATED FIRST NAME***]",
      "USER_LAST_NAME": "[***LAST NAME***]"
      }'

Change a user role:


      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/UpdateUser' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data '{
      "USER_ID": "[***USER ID***]",
      "USER_NAME": "[***USER EMAIL***]",
      "USER_AUTH_LEVEL": "ADMIN"
      }'

Delete a user:


      curl --location 'https://[***COMPANY NAME***].octopai.com/api/UserAccount/DeleteUser' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer [***ACCESS TOKEN***]' \
      --header 'Company-Host: [***COMPANY NAME***].octopai.com' \
      --data '{
      "USER_ID": "[***USER ID***]",
      "USER_NAME": "[***USER EMAIL***]",
      "USER_FIRST_NAME": "[***UPDATED FIRST NAME***]",
      "USER_LAST_NAME": "[***LAST NAME***]"
      }'

Store your accessToken securely and refresh it as needed to prevent it from being compromised. Always use HTTPS to make your requests to ensure data security during transit.

Contact Cloudera Support for more details and instructions.