Audit Logs

The audit logs endpoint allows administrators to retrieve security and activity events for compliance and monitoring purposes.

List Audit Logs

GET/api/public/v0/audit-logs

Returns a paginated list of audit log events. This endpoint uses cursor-based pagination for efficient retrieval of large datasets.

Authentication

Requires an API key with Admin role permissions. See Authentication for more details.

Restricted API Keys

You can create API keys that are restricted to only access this endpoint by naming them with the SIEM-LOG-ONLY prefix. This is useful for SIEM integrations or third-party services that only need audit log access.

For example, an API key named SIEM-LOG-ONLY-splunk or SIEM-LOG-ONLY-datadog will:

• Be allowed to access GET /api/public/v0/audit-logs
• Be blocked from accessing all other API endpoints (returns 403 Forbidden)

This provides a security best practice of least-privilege access for audit log integrations.

Subscription Requirements

This endpoint is only available on plans with the Advanced Auth feature (Business and Enterprise plans). Requests from tenants without this feature will receive a 402 Payment Required response.

Query Parameters

Parameter	Type	Required	Description	Default
after	integer	No	Cursor for pagination. Returns events with ID greater than this value.	0
count	integer	No	Number of events to return per page. Must be between 1 and 1000. Omit to use default.	100

Response Format

Status: 200 OK

{
  after: number                     // Cursor value for next page (last event ID in this response)
  count: number                     // Number of events returned in this response
  events: Array<{
    id: number                      // Unique event identifier
    user: {                         // User who performed the action (null for system events)
      id: number                    // User ID
      name: string                  // User's display name
      email: string                 // User's email address
    } | null
    action: string                  // Action type (see Action Types below)
    ip: string                      // IP address of the request
    userAgent: string               // User agent string
    createdAt: string               // ISO 8601 timestamp
    meta?: object                   // Additional context about the action (see Meta Field below)
  }>
}

Action Types

Action	Description
login	User logged in
logout	User logged out
register	New user registered
2fa_enable	Two-factor authentication enabled
2fa_disable	Two-factor authentication disabled
password_change	User changed their password
password_reset	Password was reset
request_password_reset	Password reset was requested
email_change	User changed their email address
invite_user	User was invited to the organization
cancel_invite	User invitation was cancelled
archive_project	Project was archived
unarchive_project	Project was unarchived
delete_project	Project was deleted
auth.ip_or_user_agent_changed	IP address or user agent changed during session

Meta Field

The meta field provides additional context about the action. It is omitted when empty. The structure varies by action type:

Action	Meta Fields
archive_project, unarchive_project, delete_project	project_id, project_code, project_title
email_change	old (previous email), new (new email)
invite_user, cancel_invite	invited_email, invited_role
Other actions	No meta (field omitted)

Example Request

curl \
  -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/audit-logs?count=50"

Example Response

{
  "after": 156,
  "count": 3,
  "events": [
    {
      "id": 154,
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
      },
      "action": "login",
      "ip": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "createdAt": "2025-01-28T10:30:00Z"
    },
    {
      "id": 155,
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
      },
      "action": "archive_project",
      "ip": "192.168.1.100",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "createdAt": "2025-01-28T11:00:00Z",
      "meta": {
        "project_id": "1CKgJ5HMU_2apSDSQWRw6Ys",
        "project_code": "PROJ",
        "project_title": "My Project"
      }
    },
    {
      "id": 156,
      "user": {
        "id": 2,
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "action": "email_change",
      "ip": "192.168.1.101",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
      "createdAt": "2025-01-28T12:00:00Z",
      "meta": {
        "old": "jane.old@example.com",
        "new": "jane@example.com"
      }
    }
  ]
}

Pagination

This endpoint uses cursor-based pagination for efficient retrieval:

1. Make an initial request without the after parameter to get the first page
2. Use the after value from the response as the after parameter for the next request
3. Continue until you receive fewer events than requested (end of data)

Pagination Example

# First page
curl -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/audit-logs?count=100"
# Response: { "after": 100, "count": 100, "events": [...] }

# Second page (using after value from previous response)
curl -H "Authorization: ApiKey your.api.key.here" \
  "https://your-company.your-region-code.qasphere.com/api/public/v0/audit-logs?after=100&count=100"
# Response: { "after": 156, "count": 56, "events": [...] }
# count < 100 indicates this is the last page

note

When after is 0 or omitted, the response starts from the first event of the current month. If no events exist for the current month, an empty result is returned. The after value in the response equals the input after value when there are no more events to return.

Error Responses

Status Code	Description
400	Invalid parameters (e.g., count > 1000)
401	Invalid or missing API key
402	Subscription plan lacks Advanced Auth feature
403	Insufficient permissions (non-admin access)
500	Internal server error

tip

This endpoint enables you to:

• Monitor user authentication activity
• Track security-related changes (2FA, password changes)
• Audit project lifecycle events
• Integrate with SIEM systems for compliance
• Build custom security dashboards