Audita

Technical Documentation

Integration guide and SDK references for the Audit System. Learn how to track events, verify integrity, and manage your organization.

Authentication & Authorization

The system supports two main authentication methods depending on the operation type.

X-API-KEY

Used for backend-to-backend communication, specifically for creating audits. Send it in the X-API-KEY header.

Bearer Token (JWT)

Used for administrative and reading operations. Send it as Authorization: Bearer <token>.

1. Create Audit & Bulk Create

Send audit events to the system to maintain integrity. Supports individual and bulk batching.

● URL Individual: POST /api/audits● URL Bulk: POST /api/audits/bulk● Auth: X-API-KEY (Recommended) or JWT

# Individual
curl -X POST http://localhost:3000/api/audits \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "uuid-org",
    "resourceType": "USER",
    "resourceId": "123",
    "action": "CREATE",
    "actorData": "admin-email",
    "payload": "{\"key\": \"value\"}",
    "correlationId": "optional-uuid"
  }'

# Bulk
curl -X POST http://localhost:3000/api/audits/bulk \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[{"organizationId": "..."}, {"organizationId": "..."}]'

2. Get Audit (Search & Direct)

Search and filter the audit history with pagination support.

● URL: GET /api/audits● Auth: JWT (ROLE_USER or ROLE_ADMIN)● Params: page, size, resourceType, action, actorData

curl -X GET "http://localhost:3000/api/audits?page=0&size=10&resourceType=USER" \
  -H "Authorization: Bearer <your_jwt_token>"

3. Verify Integrity

Verify that the cryptographic hash chain has not been compromised.

● URL: GET /api/audits/verify/{organizationId}● Auth: JWT (ROLE_ADMIN or Org Member)

curl -X GET http://localhost:3000/api/audits/verify/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <your_jwt_token>"

4. Member Management

Link existing users to your organization or remove them (Admins only).

● Assign: POST /api/users/assign-organization● Remove: POST /api/users/{userId}/remove-from-organization● Auth: JWT (Strictly ROLE_ADMIN)

# Assign (via Email)
curl -X POST http://localhost:3000/api/users/assign-organization \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

# Remove (via UUID)
curl -X POST http://localhost:3000/api/users/<user_id>/remove-from-organization \
  -H "Authorization: Bearer <admin_jwt>"

Audit Schema & Payload

Detailed structure of the audit object required for creation. Ensure all mandatory fields are present.

Recommended JSON Structure

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "resourceType": "USER_PROFILE",
  "resourceId": "usr_9921",
  "action": "UPDATE",
  "actorData": "admin@company.com",
  "payload": "{\"changed_fields\": [\"email\", \"role\"]}",
  "correlationId": "b6a32c-f921-4d1a-8c92"
}

Field	Type	Required	Description
organizationId	UUID	SÍ	Identificador único de la organización a la que pertenece el evento.
resourceType	String	SÍ	Tipo de entidad afectada (ej: USER, ORDER, INVOICE).
resourceId	String	SÍ	ID único de la entidad específica que fue afectada.
action	Enum	SÍ	La acción realizada. Valores: CREATE, UPDATE, DELETE, ACCESS, OTHER.
actorData	String	NO	Información de quién realizó la acción (ej: email, username o ID del sistema).
payload	JSON String	NO	Detalle técnico del cambio en formato JSON String. Ideal para guardar el "antes" y "después".
correlationId	String	NO	ID para agrupar múltiples eventos que pertenecen a un mismo flujo de negocio.

Security Summary by Endpoint

Use Case	Method	Authentication	Min. Permission
Create/Bulk Audit	POST	X-API-KEY / JWT	ROLE_ORGANIZATION
Get Audits	GET	JWT	ROLE_USER
Verify Integrity	GET	JWT	ROLE_USER (Org Member)
Assign/Remove User	POST	JWT	ROLE_ADMIN

💡 Development Notes

• Error Handling: Implementations must handle 401 Unauthorized (token expired) and 403 Forbidden (insufficient permissions).

• Payload Validation: The payload field in create audits must be a valid JSON string.

• Bulk Requests: For Go and Java, we recommend using a list of DTO objects to send the array in the POST /api/audits/bulk body.