> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Logs

> Query system audit logs

<Info>
  Query system audit logs for compliance and monitoring. Only administrators can access audit logs.
</Info>

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer <token>` - Admin JWT
</ParamField>

### Query Parameters

<ParamField query="user_id" type="string">
  Filter by user ID
</ParamField>

<ParamField query="event_type" type="string">
  Filter by event type (e.g., `PAYMENT_EXECUTED`, `USER_LOGIN`)
</ParamField>

<ParamField query="from" type="string">
  Start date (ISO 8601)
</ParamField>

<ParamField query="to" type="string">
  End date (ISO 8601)
</ParamField>

<ParamField query="limit" type="integer">
  Results limit (default: 50, max: 500)
</ParamField>

<ParamField query="offset" type="integer">
  Pagination offset
</ParamField>

***

## Response

<ResponseField name="logs" type="array">
  Array of audit log entries
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching logs
</ResponseField>

***

## Examples

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://demo.api.vultlocal.com/api/v1/audit/logs?event_type=PAYMENT_EXECUTED&limit=50" \
    -H "Authorization: Bearer ADMIN_JWT"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "logs": [
      {
        "id": "log_123",
        "event_type": "PAYMENT_EXECUTED",
        "actor": "sub_abc123",
        "actor_type": "subscriber",
        "details": {
          "amount": 5000,
          "currency": "SLE",
          "recipient": "sub_xyz789"
        },
        "ip_address": "192.168.1.1",
        "timestamp": "2025-01-15T10:30:00Z"
      },
      {
        "id": "log_124",
        "event_type": "USER_LOGIN",
        "actor": "admin@olive.sl",
        "actor_type": "admin",
        "details": {
          "success": true,
          "user_agent": "Mozilla/5.0..."
        },
        "ip_address": "10.0.0.1",
        "timestamp": "2025-01-15T10:25:00Z"
      }
    ],
    "total": 1500
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "success": false,
    "error": "Not authorized to access audit logs",
    "code": "FORBIDDEN"
  }
  ```
</ResponseExample>

***

## Event Types

| Event Type              | Description                |
| ----------------------- | -------------------------- |
| `USER_LOGIN`            | User login attempt         |
| `USER_LOGOUT`           | User logout                |
| `USER_CREATED`          | New user created           |
| `PAYMENT_EXECUTED`      | Payment processed          |
| `TRANSFER_COMPLETED`    | Transfer completed         |
| `SUBSCRIBER_REGISTERED` | New subscriber             |
| `SUBSCRIBER_BLOCKED`    | Subscriber blocked         |
| `CARD_LINKED`           | Card linked to subscriber  |
| `COMPLIANCE_ALERT`      | Compliance alert triggered |
| `API_KEY_CREATED`       | API key generated          |

***

## Errors

| Status | Code              | Description                   |
| ------ | ----------------- | ----------------------------- |
| 400    | `INVALID_REQUEST` | Invalid query parameters      |
| 401    | `UNAUTHORIZED`    | Not authenticated             |
| 403    | `FORBIDDEN`       | Not authorized to access logs |


## OpenAPI

````yaml olive-openapi.json GET /audit/logs
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /audit/logs:
    get:
      tags:
        - Admin
      summary: Audit Logs
      description: Query system audit logs
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          schema:
            type: string
        - name: event_type
          in: query
          required: false
          schema:
            type: string
        - name: from
          in: query
          required: false
          schema:
            type: string
        - name: to
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      description: >-
        JWT token from admin login for administrative operations. Format:
        'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
      type: apiKey
      name: Authorization
      in: header

````