Authentication

API Key model

API keys are the primary authentication for event ingestion. They follow these principles:

Format

Keys are generated as mtr_ followed by 48 hex characters:

mtr_a1b2c3d4e5f6789012345678901234567890abcdef01

Storage

Keys are never stored in plaintext. The system stores:

• A SHA-256 hash of key:pepper for lookup
• A preview (mtr_a1b2...ef01) for display in the dashboard

Lifecycle

1. Creation: Generated when a project is created, or via the "Create API Key" dialog
2. Usage: Sent with every request to /api/collect
3. Rotation: Create a new key → migrate your apps → revoke the old key
4. Revocation: Revoked keys immediately stop accepting events

Security best practices

• Never commit API keys to source control. Use environment variables.
• Use separate keys for production and development
• Rotate keys periodically for production apps
• Monitor "Last used" in the dashboard to detect stale keys

Protected routes

/dashboard/**  → requires dashboard authentication
/api/projects  → requires dashboard authentication
/api/dashboard → requires dashboard authentication

Public routes

/              → landing page (public)
/docs/**       → documentation (public)
/api/collect   → event ingestion (API key auth)