Archiva API

Archiva is a secure audit logging service designed to help you maintain a complete, tamper-proof record of all important actions in your application. Whether you need to track user actions for compliance, debug issues by seeing what happened, or provide transparency to your customers, Archiva gives you a reliable, secure way to log and retrieve audit events.

Why Use Archiva?

Compliance and Accountability

Many industries require detailed audit logs for compliance (SOC 2, HIPAA, GDPR, etc.). Archiva helps you meet these requirements by providing an immutable record of who did what, when, and why. This is crucial for demonstrating due diligence and maintaining regulatory compliance.

Debugging and Troubleshooting

When something goes wrong in production, audit logs help you understand exactly what happened. Instead of guessing, you can see the sequence of events that led to an issue, making debugging faster and more accurate.

Customer Transparency

Modern applications often show activity logs to users (like GitHub's activity feed or banking transaction history). Archiva makes it easy to build these features by providing a ready-made API for retrieving and displaying events.

Security and Trust

By encrypting events at rest and providing secure access controls, Archiva ensures your audit data remains protected. Even if your database is compromised, encrypted audit logs remain secure.

Key Features

  • End-to-end encryption: All events are encrypted at rest using project-specific keys, ensuring your audit data remains secure even if your infrastructure is compromised. This is essential for protecting sensitive information and meeting security compliance requirements.

  • Idempotent ingestion: Network issues, retries, and webhook failures won't create duplicate events. You can safely retry requests without worrying about creating duplicate audit entries, which is critical for maintaining accurate records.

  • Rate limiting: Built-in protection prevents abuse and ensures fair usage across all customers. This protects both your application and the Archiva service from being overwhelmed by excessive requests.

  • Flexible querying: Find exactly what you need quickly. Filter by user, entity, action type, tenant, or search across multiple fields. This makes it easy to answer questions like "What did user X do?" or "What happened to invoice Y?"

  • Cursor-based pagination: Efficiently navigate through large result sets without performance degradation. Unlike offset-based pagination, cursor-based pagination remains fast even with millions of events, making it practical for applications with high event volumes.

Base URL

https://api.archiva.app

For local development:

http://localhost:3000

Getting Started

To start using Archiva, you'll need an API key. Think of this as your application's identity when talking to Archiva—it proves you're authorized to create and read events for your project.

Setting Up Your API Key

For security reasons, API keys should never be hardcoded in your application. Instead, they should be stored as environment variables, which keeps them out of your codebase and makes it easy to use different keys for development and production.

Set the ARCHIVA_SECRET_KEY environment variable with your API key:

ARCHIVA_SECRET_KEY=pk_test_your_api_key_here

Why environment variables?

  • They keep secrets out of your code repository
  • They allow different keys for development, staging, and production
  • They make it easy to rotate keys without code changes
  • They're the industry standard for managing sensitive credentials

Where to set it:

  • Development: Store in .env.local (Next.js) or .env file (make sure it's in .gitignore)
  • Production: Set as an environment variable in your hosting platform (Vercel, Railway, AWS, etc.)

Your First Event

Let's create your first audit event. This example logs when a user updates an invoice:

curl -X POST https://api.archiva.app/api/ingest/event \
  -H "Authorization: Bearer pk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "actionKey": "invoice.update",
    "entityType": "invoice",
    "entityId": "inv_12345",
    "actorType": "user",
    "actorId": "usr_123"
  }'

What this does: This creates an audit event that records "user usr_123 updated invoice inv_12345". The event is immediately encrypted and stored securely. You can later retrieve this event (and others) to see the complete history of what happened to this invoice.

Why these fields matter:

  • actionKey: Describes what happened (e.g., "invoice.update", "user.login", "payment.processed")
  • entityType and entityId: Identifies what was affected (the invoice in this case)
  • actorType and actorId: Identifies who performed the action (the user in this case)

This structure makes it easy to answer questions like "What did user X do?" or "What happened to invoice Y?" by filtering on these fields.

Note: We use the Authorization: Bearer header (standard HTTP authentication) rather than custom headers. This follows industry best practices and works seamlessly with most HTTP clients and libraries.