Audit Logs

Audit logs in Matia allow users to monitor, record, and review platform activity for compliance, security, and operational transparency. This guide describes how to retrieve audit logs, including how to generate a secure API token using the UI and use it to access logs via Matia’s API.

Overview

Matia’s audit logs provide a detailed record of key events, system changes, and user actions within your organization. Audit logs can help meet compliance requirements, support investigations, and improve overall accountability.

Prerequisites

• An active Matia account with Admin permissions
• API access enabled for your organization

Step 1: Retrieve an API Token via the UI

To securely access audit logs, you’ll need to generate an API token using the Matia UI.

Instructions

1. Log in to your Matia environment.
2. Navigate to Settings > Admin > API Tokens.
3. Click Generate Token.
4. Provide a description for the token (e.g., audit-logs-access).
5. Select the Admin role.
6. Click Create.
7. Copy your new API token. Store it securely, as it will not be shown again.

Step 2: Retrieve Audit Logs via the API

After generating your token, you can programmatically retrieve audit log data using Matia’s API.

Endpoint

GET https://api.matia.io/v1/admin/audit-logs

Required Headers

Header	Value
x-api-key	YOUR_API_TOKEN
Content-Type	application/json

Query Parameters

• created_from (optional, ISO8601): Start of time window
• created_to (optional, ISO8601): End of time window
• user_id (optional): Filter by user
• email (optional): Filter by user email

Example Request (cURL)

curl -X GET "https://api.matia.io/v1/admin/audit-logs" \
  -H "x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.MockTokenValueForDemo.aBcDeF123" \
  -H "Content-Type: application/json"

Sample Response

{
  "audit-logs": [
    {
      "timestamp": "2025-07-16T14:02:22.523Z",
      "user_agent": "Mozilla/5'.0 (Macintosh; Intel ...",
      "user_email": "[e-mail]",
      "action": "User logged in",
      "description": "User logged in to the application.",
      "severity": "info",
    },
    {
      "timestamp": "2025-07-15T17:54:47.679Z",
      "user_agent": "Mozilla/5'.0 (Macintosh; Intel ...",
      "user_email": "[e-mail]",
      "action": "Created Access Token",
      "description": "Create new Access Token on the product",
      "severity": "info",
    }
  ]
}

Troubleshooting

• 401 Unauthorized: Check that your API token is valid and has the correct scopes.
• 403 Forbidden: You may lack required permissions.
• No logs returned: Confirm correct query parameters and available data range.

FAQ

Q: Can I access logs older than 30 days?

A: Matia retention policy is limited for 30 days. For long-term storage, export logs to your preferred storage or SIEM solution.

Q: Can I filter logs by a specific user ID or user email?

A: Yes, use the user_id and user_email query parameters to apply required filters.

For further assistance, contact Matia Support.