Skip to content

Audit Log API

The Audit Log records security-relevant events on the Canvus server -- user sign-ins, account changes, canvas operations, permission modifications, and administrative actions. Use this API to retrieve and export audit events for compliance, troubleshooting, and security monitoring.

Authentication: All endpoints require administrator authentication.

Streaming: The audit log endpoints do not support ?subscribe for live updates. Use polling or periodic CSV export instead.

Audit event object

Each audit event captures who did what, to which resource, and when.

Fields:

  • id (integer) -- unique event identifier
  • created_at (string) -- ISO 8601 timestamp of when the event occurred
  • author_id (integer) -- user ID of the person who performed the action
  • author_name (string) -- display name of the author at the time of the event
  • action (string) -- the type of action performed (e.g., "login", "create", "update", "delete", "block", "approve")
  • target_type (string) -- the type of resource affected (e.g., "User", "Canvas", "Group", "ServerConfig")
  • target_id (string) -- the ID of the affected resource
  • target_name (string) -- display name of the affected resource at the time of the event
  • details (string) -- additional context about the event, if available

Example:

{
  "id": 5042,
  "created_at": "2025-03-28T14:05:12.003Z",
  "author_id": 1000,
  "author_name": "Admin",
  "action": "block",
  "target_type": "User",
  "target_id": "1002",
  "target_name": "Alice Chen",
  "details": ""
}

List Audit Events

Returns paginated audit events matching the specified filters. Events are sorted from newest to oldest.

GET /api/v1/audit-log

Authentication: Admin required.

Streaming: Not supported.

Query parameters (all optional):

  • created_after (string) -- ISO 8601 timestamp. Include only events created after this time.
  • created_before (string) -- ISO 8601 timestamp. Include only events created before this time.
  • target_type (string) -- filter by resource type (e.g., "User", "Canvas", "Group")
  • target_id (string) -- filter by the ID of the affected resource
  • author_id (string) -- filter by the ID of the user who performed the action
  • per_page (integer) -- number of results per page. Server default applies if omitted.
  • cursor (integer) -- page offset for pagination. Obtain this value from the Link response header.
curl -H "Private-Token: YOUR_TOKEN" \
  https://canvus.example.com/api/v1/audit-log

Response (200 OK):

The response body is a JSON array of audit event objects. Pagination links are provided in the Link HTTP response header.

[
  {
    "id": 5042,
    "created_at": "2025-03-28T14:05:12.003Z",
    "author_id": 1000,
    "author_name": "Admin",
    "action": "block",
    "target_type": "User",
    "target_id": "1002",
    "target_name": "Alice Chen",
    "details": ""
  },
  {
    "id": 5041,
    "created_at": "2025-03-28T13:58:30.117Z",
    "author_id": 1002,
    "author_name": "Alice Chen",
    "action": "login",
    "target_type": "User",
    "target_id": "1002",
    "target_name": "Alice Chen",
    "details": ""
  }
]

Pagination

The Link response header contains URLs for navigating between pages:

Link: <https://canvus.example.com/api/v1/audit-log?cursor=100&per_page=20>; rel="next",
      <https://canvus.example.com/api/v1/audit-log?cursor=0&per_page=20>; rel="prev"

Follow the rel="next" link to fetch the next page. When there is no next link, you have reached the end of the results.

Filtering examples

Events from a specific time range:

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/audit-log?created_after=2025-03-01T00:00:00Z&created_before=2025-03-31T23:59:59Z"

All events for a specific user:

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/audit-log?target_type=User&target_id=1002"

Events performed by a specific administrator:

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/audit-log?author_id=1000"

Custom page size:

curl -H "Private-Token: YOUR_TOKEN" \
  "https://canvus.example.com/api/v1/audit-log?per_page=50"

Error responses:

  • 403 Forbidden -- caller is not an administrator

Export Audit Log as CSV

Exports audit events as a CSV file download. Accepts the same filter parameters as the list endpoint. The entire filtered result set is returned in a single response (no pagination).

GET /api/v1/audit-log/export-csv

Authentication: Admin required.

Streaming: Not supported (the endpoint uses streaming internally to generate the file, but the client receives a complete file download).

Query parameters (all optional):

  • created_after (string) -- ISO 8601 timestamp. Include only events created after this time.
  • created_before (string) -- ISO 8601 timestamp. Include only events created before this time.
  • target_type (string) -- filter by resource type
  • target_id (string) -- filter by the ID of the affected resource
  • author_id (string) -- filter by the ID of the user who performed the action
curl -H "Private-Token: YOUR_TOKEN" \
  -o audit-log.csv \
  https://canvus.example.com/api/v1/audit-log/export-csv

Response: The server returns the CSV file with Content-Type: text/csv and a Content-Disposition header for download.

Export with date filter:

curl -H "Private-Token: YOUR_TOKEN" \
  -o march-2025-audit.csv \
  "https://canvus.example.com/api/v1/audit-log/export-csv?created_after=2025-03-01T00:00:00Z&created_before=2025-03-31T23:59:59Z"

Error responses:

  • 403 Forbidden -- caller is not an administrator