TamperTrail — API Reference

Base URL: http://your-host (all traffic enters via Nginx on port 80) API prefix: Every endpoint starts with /v1

Table of Contents

1. Authentication
2. Log API — POST /v1/log
   • 2.1 Payload Schema
   • 2.2 Tags vs Metadata
   • 2.3 Severity Auto-Derivation
   • 2.4 Auto-Captured Fields
   • 2.5 Requests & Responses
   • 2.6 Integration Examples
3. Health Check — GET /health
4. HTTP Status Code Reference
5. Rate Limits

1. Authentication

TamperTrail uses two separate authentication systems. Never mix them up.

API Key — For Sending Logs (this is what you need)

Create a key in the dashboard under API Keys → Create Key. The raw key is shown only once.

Pass it as an HTTP header on every request:

X-API-Key: vl_a1b2c3d4e5f6...

Keys are stored Argon2-hashed. A lost key cannot be recovered — revoke it and create a new one.

Never hardcode an API key. Use an environment variable: TAMPERTRAIL_API_KEY=vl_...

JWT Session — For the Dashboard

The browser dashboard handles this automatically via an HTTPOnly cookie (tampertrail_token) set at login. Tokens expire after 24 hours. One active session per user — logging in from a new location ends the previous session. You don't need to worry about this for log integration.

2. Log API — POST /v1/log

Purpose: Ingest a single audit log entry. Auth: X-API-Key header Response: 202 Accepted — log is written to the WAL on disk and queued for batch DB insertion. The response does not wait for the DB write.

2.1 Payload Schema

Every log entry sent to TamperTrail can contain up to 12 fields. Only 2 are required.

Field-by-Field Examples

actor — who did it:

"user:alice@acme.com"       — a logged-in user
"service:billing-worker"    — a backend service/microservice
"cron:nightly-sync"         — a scheduled job
"api:mobile-app"            — an API consumer
"admin:superadmin"          — an admin performing a privileged action

action — what happened:

"order.created"             — resource.verb format
"payment.refunded"          — financial event
"user.login.failed"         — nested context
"file.deleted"              — destructive action (auto-detected as critical)
"api_key.revoked"           — security event

message — write for humans:

✅ "Order ORD-1001 created — AirPods Pro worth ₹24,900 shipping from Mumbai to Delhi"
✅ "Payment of $149.00 processed via Stripe for Pro plan upgrade"
❌ "order created"         — too vague, not useful for investigation
❌ "{json blob here}"      — put structured data in tags/metadata, not message

target_type + target_id — identify the resource:

target_type: "order"        target_id: "ORD-1001"
target_type: "invoice"      target_id: "inv_9f2a3b4c"
target_type: "user"         target_id: "usr_alice_8821"
target_type: "document"     target_id: "doc_annual_report_2025"
target_type: "api_key"      target_id: "vl_a1b2"

status — what happened:

"success"     — action completed
"failed"      — action did not complete
"timeout"     — action timed out
"200"         — HTTP 200 OK
"404"         — resource not found
"500"         — server error

environment — deployment context:

"production"  — live system
"staging"     — pre-production testing
"test"        — automated test environment
"development" — local development

2.2 The tags vs. metadata Decision

This is the most important design decision when integrating TamperTrail.

Decision rule — ask yourself:

• Would you be comfortable showing this on a team dashboard? → tags
• Does it contain PII, secrets, credentials, stack traces, or internal details? → metadata

tags examples (searchable, visible):

{
  "payment_provider": "stripe",
  "amount_usd": "149.00",
  "plan": "pro",
  "region": "eu-west-1",
  "browser": "Chrome"
}

metadata examples (encrypted, never shown):

{
  "card_last4": "4242",
  "stripe_charge": "ch_3abc123def",
  "billing_email": "alice@acme.com",
  "full_request_body": { "..." },
  "stack_trace": "Traceback (most recent call last)..."
}

2.3 Severity Auto-Derivation

If you don't provide a level field, TamperTrail automatically derives severity by scanning your action string for keywords.

How level maps to dashboard severity:

When level is omitted — auto-detection kicks in:

TamperTrail scans the action string for these keywords:

Examples:

action: "user.deleted"      → auto-derived: critical (contains "delete")
action: "profile.updated"   → auto-derived: warning  (contains "update")
action: "order.created"     → auto-derived: info     (no trigger words)
action: "api_key.revoked"   → auto-derived: critical (contains "revoke")

Explicit level always wins. If you send "level": "INFO" with "action": "user.deleted", the log will be info, not critical.

2.4 Auto-Captured Fields

These fields are captured by the server automatically. You do not need to provide them.

2.5 Requests & Responses

Minimal Request — Only the 2 required fields

{
  "actor": "user:alice@acme.com",
  "action": "document.downloaded"
}

Full Request — Every field TamperTrail accepts

{
  "actor":       "user:alice@acme.com",
  "action":      "payment.processed",
  "level":       "INFO",
  "message":     "Payment of $149.00 processed via Stripe for Pro plan upgrade.",
  "target_type": "invoice",
  "target_id":   "inv_9f2a3b4c",
  "status":      "success",
  "environment": "production",
  "source_ip":   "203.0.113.42",
  "request_id":  "req_trace_abc123",
  "tags": {
    "payment_provider": "stripe",
    "amount_usd":       "149.00",
    "plan":             "pro"
  },
  "metadata": {
    "card_last4":    "4242",
    "stripe_charge": "ch_3abc123def",
    "billing_email": "alice@acme.com"
  }
}

Success Response

{ "status": "accepted", "message": "Log queued for processing" }

Error Responses

2.6 Integration Examples

While you can write standard HTTP requests directly to /v1/log, we recommend using our official drop-in snippets to ensure connection pooling and non-blocking execution.

👉 View Integration Guide

3. Health Check — GET /health

Purpose: Returns the live status of the server, database, and ingestion queue. No authentication required. Suitable for load balancer health probes.

Auth: None

Response: 200 OK

{
  "status": "ok",
  "db": "ok",
  "queue_depth": 0,
  "wal_entries": 0
}

If the database is unreachable, "db" will be "error" and the status code will be 503.

4. HTTP Status Code Reference

5. Rate Limits

Rate limiting is enforced by Nginx before requests reach the application server. Limits are per IP address.

When a limit is exceeded, Nginx returns 429 Too Many Requests with a Retry-After header.

For high-volume ingestion above 100 req/min, batch your logs client-side into arrays and send them in fewer, larger requests — or contact us about a Pro ingestion upgrade.