Authentication

Every request to the Archiva API must include authentication to prove you're authorized to access your project's events. This ensures that only you can create and read events for your project, protecting your audit data from unauthorized access.

Why Authentication Matters

Without authentication, anyone could read or create events in your project, which would be a serious security risk. API keys act as a secret password that proves your application is authorized to interact with Archiva on behalf of your project. Think of it like a key to a safe—only those with the key can access what's inside.

Understanding API Keys

Your API key is a unique identifier that proves your application is authorized to access your project's events. It's like a password, but designed specifically for programmatic access.

API Key Format

API keys follow a predictable format that helps you understand what type of key you're using:

pk_<env>_<random>
  • pk_ indicates this is a project key
  • <env> tells you the environment: test for development/testing, live for production
  • <random> is a secure random string that makes each key unique

Why separate test and live keys? This separation allows you to:

  • Test your integration safely without affecting production data
  • Use different rate limits and quotas for development vs. production
  • Rotate keys independently (you might rotate test keys more frequently)
  • Keep production keys more secure (fewer people need access to them)

Examples:

  • Test key: pk_test_h0Sp-ZscbiYvidtslqkM5A (use this for development)
  • Live key: pk_live_xyz123abc456def789 (use this for production)

How to Authenticate

You have two ways to provide your API key with each request. Both work identically, but we recommend the first method for better compatibility and following industry standards.

Method 1: Authorization Bearer Token (Recommended)

This is the standard way to authenticate HTTP requests, used by OAuth, JWT tokens, and most modern APIs. It's widely supported by HTTP clients, libraries, and tools.

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 '{...}'

Why this method?

  • It's the industry standard for HTTP authentication
  • Works seamlessly with most HTTP clients and libraries
  • Familiar to developers who've used other APIs
  • Better support in tools like Postman, Insomnia, and HTTP libraries

Method 2: X-Project-Key Header (Alternative)

If you prefer a custom header, you can use X-Project-Key instead:

curl -X POST https://api.archiva.app/api/ingest/event \
  -H "X-Project-Key: pk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}'

When to use this: Some legacy systems or custom integrations might find custom headers easier to work with. However, for new integrations, we recommend the Bearer token method.

Storing Your API Key Securely

Never hardcode your API key in your source code. Instead, store it as an environment variable. This keeps your secrets out of your codebase and makes it easy to use different keys for different environments.

Why Environment Variables?

  1. Security: If your code repository is ever compromised, your API keys won't be exposed
  2. Flexibility: Easy to use different keys for development, staging, and production
  3. Compliance: Many security standards require secrets to be stored separately from code
  4. Best Practice: This is how all major APIs (Stripe, Twilio, AWS, etc.) recommend storing credentials

Set the ARCHIVA_SECRET_KEY environment variable:

ARCHIVA_SECRET_KEY=pk_test_your_api_key_here

Where to set it:

  • Development: In .env.local (Next.js) or .env file at your project root
  • Production: As an environment variable in your hosting platform (Vercel, Railway, AWS, etc.)

Important reminders:

  • Make sure .env.local or .env is in your .gitignore file
  • Restart your development server after adding or changing the variable (environment variables are loaded at startup)
  • Never commit environment files to version control

Security Best Practices

Protecting your API keys is crucial for maintaining the security of your audit logs. Here's why each practice matters:

  1. Never expose API keys in client-side code or public repositories

    • If someone gets your API key, they can create or read events in your project
    • Client-side code (JavaScript in browsers) is visible to anyone
    • Public repositories are scanned by bots looking for exposed secrets

  2. Use environment variables to store API keys

    • Keeps secrets separate from your code
    • Makes it easy to rotate keys without code changes
    • Prevents accidental exposure in code reviews or commits

  3. Rotate API keys regularly, especially if compromised

    • If a key is ever exposed, rotating it immediately prevents unauthorized access
    • Regular rotation limits the damage if a key is compromised
    • Many compliance standards require periodic key rotation

  4. Use test keys for development and live keys only for production

    • Test keys let you experiment safely without affecting production data
    • If a test key is compromised, your production data remains safe
    • Different rate limits and quotas prevent development work from affecting production

  5. Restrict API key access to only the services that need it

    • Follow the principle of least privilege: only give access to what's needed
    • If one service is compromised, others remain protected
    • Makes it easier to identify which service is making requests

  6. Prefer Authorization Bearer method

    • Standard method is more widely supported and tested
    • Better compatibility with HTTP clients and libraries
    • Follows industry best practices

API Key Status

Your API keys can be in different states, which control whether they can be used:

  • active: The key is valid and can be used to create and read events. This is the normal state for keys you're actively using.

  • revoked: The key has been disabled and cannot be used. This is useful if:

    • You suspect the key has been compromised
    • You want to temporarily disable access
    • A team member who had access has left your organization

  • retired: The key has been permanently retired (legacy status). Similar to revoked, but indicates the key won't be reactivated.

Why revoke keys? If you ever suspect a key has been exposed or compromised, revoking it immediately prevents unauthorized access. You can then create a new key and update your application to use it.

Requests with revoked or retired keys will receive a 403 Forbidden response, clearly indicating the key is no longer valid.

Frontend Tokens (For Read-Only Access)

If you're building a frontend application that needs to display audit events to users, you might not want to expose your main API key to the browser (which would be a security risk). Instead, you can use short-lived JWT tokens that provide read-only access.

Why Frontend Tokens?

  • Security: Your main API key never leaves your server
  • Limited scope: Tokens can only read events, not create them
  • Short-lived: Tokens expire quickly (typically 90 seconds), limiting damage if intercepted
  • Project-scoped: Each token is tied to a specific project

How They Work

Your backend generates a JWT token with read-only permissions and sends it to your frontend. The frontend uses this token to fetch events directly from the Archiva API. When the token expires, your frontend requests a new one from your backend.

curl -X GET https://api.archiva.app/api/events \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

When to use: If you're building a user-facing activity log or timeline feature, frontend tokens let you securely display events without exposing your main API key. The Next.js SDK handles this automatically for you.

Error Responses

Missing API Key

{
  "error": "Missing API key. Provide Authorization: Bearer token or X-Project-Key header"
}

Status Code: 401 Unauthorized

Invalid API Key Format

{
  "error": "Invalid API key format"
}

Status Code: 401 Unauthorized

Invalid or Non-existent API Key

{
  "error": "Invalid API key"
}

Status Code: 401 Unauthorized

Revoked API Key

{
  "error": "API key has been revoked"
}

Status Code: 403 Forbidden