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
  • action (string) -- the type of action performed (e.g., "Login", "Create resource", "Update user")
  • author_id (integer or null) -- user ID of the person who performed the action, or null when there is no acting user (for example, a failed sign-in)
  • details (string) -- additional context about the event, if available
  • ip_address (string) -- IP address of the client that performed the action
  • target_id (string or null) -- the ID of the affected resource, or null when the event has no specific target
  • target_type (string) -- the type of resource affected (e.g., "user", "canvas", "group")

Example:

{
  "action": "Login",
  "author_id": 1000,
  "details": "{\"method\":\"password\"}",
  "id": 1,
  "ip_address": "127.0.0.1",
  "target_id": "1000",
  "target_type": "user"
}

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 at or after this time.
  • created_before (string) -- ISO 8601 timestamp. Include only events created at or 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 (integer) -- filter by the ID of the user who performed the action. Must be a non-negative integer.
  • per_page (integer) -- number of results per page. Server default applies if omitted.
  • cursor (integer) -- the event ID to resume from. Requires per_page. Copy this value from the next link in the Link response header rather than computing it.
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.

[
  {
    "action": "Update user",
    "author_id": 1000,
    "details": "{\"changed\":{\"blocked\":true}}",
    "id": 5042,
    "ip_address": "10.0.1.5",
    "target_id": "1002",
    "target_type": "user"
  },
  {
    "action": "Login",
    "author_id": 1000,
    "details": "{\"method\":\"password\"}",
    "id": 1,
    "ip_address": "127.0.0.1",
    "target_id": "1000",
    "target_type": "user"
  }
]

Pagination

When more results are available, the Link response header contains the URL of the next page:

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

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 at or after this time.
  • created_before (string) -- ISO 8601 timestamp. Include only events created at or before this time.
  • target_type (string) -- filter by resource type
  • target_id (string) -- filter by the ID of the affected resource
  • author_id (integer) -- filter by the ID of the user who performed the action. Must be a non-negative integer.
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.

Current behavior

The server does not yet set Content-Type: text/csv or a filename explicitly, so the type your client sees may differ. Treat the body as CSV regardless. This is being corrected.

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