Get audit logs for entity

GET

/api/v1/audit/entity/{entityType}/{entityId}

const url = 'http://localhost:3000/api/v1/audit/entity/Device/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?userId=550e8400-e29b-41d4-a716-446655440000&apiKeyId=550e8400-e29b-41d4-a716-446655440001&action=CREATE&action=UPDATE&success=true&startDate=2024-01-01T00%3A00%3A00Z&endDate=2024-12-31T23%3A59%3A59Z&ipAddress=192.168.1.100&search=device-001&page=1&limit=50&cursor=eyJpZCI6IjEyMzQifQ%3D%3D';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/api/v1/audit/entity/Device/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?userId=550e8400-e29b-41d4-a716-446655440000&apiKeyId=550e8400-e29b-41d4-a716-446655440001&action=CREATE&action=UPDATE&success=true&startDate=2024-01-01T00%3A00%3A00Z&endDate=2024-12-31T23%3A59%3A59Z&ipAddress=192.168.1.100&search=device-001&page=1&limit=50&cursor=eyJpZCI6IjEyMzQifQ%3D%3D' \
  --header 'X-API-Key: <X-API-Key>'

Retrieves audit logs for a specific entity.

Authorizations

api-key
bearer

Parameters

Path Parameters

entityType

required

string

Example

Device

Entity type (e.g., Device, User)

entityId

required

string format: uuid

Entity UUID

Query Parameters

userId

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

Filter by user ID

apiKeyId

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440001

Filter by API key ID

action

Array<string>

Allowed values: CREATE READ UPDATE DELETE LOGIN LOGOUT LOGIN_FAILED PERMISSION_GRANTED PERMISSION_DENIED EXPORT IMPORT BULK_UPDATE BULK_DELETE PASSWORD_CHANGE API_KEY_CREATED API_KEY_REVOKED CERTIFICATE_ISSUED CERTIFICATE_REVOKED DEPLOYMENT_STARTED DEPLOYMENT_COMPLETED DEPLOYMENT_FAILED DEPLOYMENT_ROLLED_BACK DEVICE_ONBOARDING_REJECTED DEVICE_CAPABILITY_REPORT_REJECTED DEVICE_STATUS_REPORT_REJECTED DEVICE_DESIRED_STATE_FETCH_REJECTED DEVICE_ONBOARDING_REJECTED_SUMMARY

Example

[
  "CREATE",
  "UPDATE"
]

Filter by audit action type(s)

success

boolean

Example

true

Filter by success status

startDate

string format: date-time

Example

2024-01-01T00:00:00Z

Filter logs from this date

endDate

string format: date-time

Example

2024-12-31T23:59:59Z

Filter logs until this date

ipAddress

string

Example

192.168.1.100

Filter by IP address

search

string

Example

device-001

Full-text search in entity name and error message

page

number

default: 1 >= 1

Example

Page number

limit

number

default: 50 >= 1 <= 100

Example

Number of results per page

cursor

string

Example

eyJpZCI6IjEyMzQifQ==

Cursor for cursor-based pagination

Responses

200

Audit logs retrieved successfully

application/json

object

data

required

List of audit log entries

Array<object>

object

required

Unique audit log identifier

string format: uuid

organizationId

required

Organization ID

string format: uuid

userId

User ID who performed the action

string format: uuid

userName

Display name of the user at the time of the action. Captured at write time so audit entries remain readable after the user is deleted.

string

apiKeyId

API key ID used for the action

string format: uuid

apiKeyName

Display name of the API key at the time of the action.

string

action

required

Type of action performed

string

entityType

required

Entity type that was affected

string

entityId

ID of the affected entity

string format: uuid

entityName

Human-readable name of the affected entity

string

beforeState

State of the entity before the change

object

key

additional properties

any

afterState

State of the entity after the change

object

key

additional properties

any

changedFields

required

List of fields that were changed

Array<string>

ipAddress

IP address of the client

string

userAgent

User agent of the client

string

requestId

Request correlation ID

string

sessionId

Session ID

string

success

required

Whether the action was successful

boolean

errorMessage

Error message if action failed

string

metadata

Additional metadata

object

key

additional properties

any

createdAt

required

When the audit log was created

string format: date-time

meta

required

Pagination metadata

object

total

required

Total number of matching records

number

page

required

Current page number

number

limit

required

Number of records per page

number

hasMore

required

Whether more records are available

boolean

nextCursor

Cursor for next page

string

Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "550e8400-e29b-41d4-a716-446655440001",
      "userId": "550e8400-e29b-41d4-a716-446655440002",
      "userName": "Alice Admin",
      "apiKeyId": "550e8400-e29b-41d4-a716-446655440003",
      "apiKeyName": "ci-publisher",
      "action": "CREATE",
      "entityType": "Device",
      "entityId": "550e8400-e29b-41d4-a716-446655440004",
      "entityName": "Production Gateway 1",
      "beforeState": {
        "status": "OFFLINE",
        "name": "Old Name"
      },
      "afterState": {
        "status": "ONLINE",
        "name": "New Name"
      },
      "changedFields": [
        "status",
        "name"
      ],
      "ipAddress": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "requestId": "req-123456",
      "sessionId": "sess-789012",
      "success": true,
      "errorMessage": "Permission denied",
      "metadata": {
        "source": "api",
        "version": "1.0"
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 50,
    "hasMore": true,
    "nextCursor": "eyJpZCI6IjEyMzQifQ=="
  }
}

401

Unauthorized

403

Forbidden — caller lacks required permission