Retrieve Audit Events

The Retrieve Audit Events endpoint returns the audit log for a specific container.

Audit events provide a complete record of container activity, including successful access, denied access, policy updates, and deletion.

Endpoint

GET /users/{user_id}/containers/{container_id}/events

Base URL:

https://share.locktera.com/api/v1

Full request URL example:

https://share.locktera.com/api/v1/users/USER_ID/containers/CONTAINER_ID/events

Authentication

All requests must include a valid API key in the Authorization header.

Example request:

curl -X GET $BASE_URL/users/USER_ID/containers/CONTAINER_ID/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Authentication and authorization are verified before audit records are returned.

Path Parameters

container_id
Required. The unique identifier of the container.

Example:

123e4567-e89b-12d3-a456-426614174000

Example Success Response

[
  {
    "org_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "123e4567-e89b-12d3-a456-426614174001",
    "ts": "2025-01-01T00:00:00Z",
    "user": "user@company.com",
    "action": "container.create",
    "detail": { ... }
  },
  {
    "org_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "123e4567-e89b-12d3-a456-426614174001",
    "ts": "2025-01-01T01:00:00Z",
    "user": "viewer@example.com",
    "action": "container.load",
    "detail": { ... }
  },
  {
    "org_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "123e4567-e89b-12d3-a456-426614174001",
    "ts": "2025-01-01T01:00:00Z",
    "user": "viewer@example.com",
    "action": "object.load",
    "detail": { ... }
  }
] 

Event Fields

Each audit event includes:

org_id
Unique identifier for the container's creating user.

container_id

Unique identifier of the container.

ts

ISO8601 timestamp when the event occurred.

user

Email address of the viewer who performed the action.

action

The action that occurred.

detail

Structured detail about the action that occurred. What data is present will depend on the type of action.

Example Error Responses

HTTP 404 Not Found

{
  "error": "not_found",
  "message": "Container not found"
}

HTTP 401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

HTTP 403 Forbidden

{
  "error": "access_denied",
  "message": "You do not have permission to view audit events for this container"
}

What Is Logged

Audit events are created when:

• A container is created
• A container is decoded
• A decode attempt is denied
• DRM policies are updated
• A container is deleted

Audit logging cannot be disabled.

Important Notes

• Audit events include both successful and denied operations
• Audit logs are immutable and cannot be modified through the API.
• Audit logs are accessible only to authorized users
• Audit logs support compliance, monitoring, and forensic analysis

Audit events are cryptographically associated with container operations.

Related Endpoints

Get Container Metadata

GET /users/{user_id}/containers/{container_id}

Retrieve DRM Policy

GET /users/{user_id}/containers/{container_id}/drm

Decode Container Manifest

GET /users/{user_id}/containers/{container_id}/decode