Authentication

Mimic supports session authentication for user traffic and API key authentication for worker callbacks.

User session auth

• Applies to /app/* and most /api/* routes.
• Session cookie is set after login.
• Route handlers read event.locals.user and reject unauthenticated requests.

Worker and service auth

Some machine endpoints require explicit API keys or signed webhook verification.

Typical patterns:

• x-api-key header for trusted service-to-service calls
• Stripe signature verification for billing webhooks
• x-mimic-signature HMAC verification for worker webhook payloads (for example claim results)
• x-cron-key or Authorization: Bearer for cron-triggered maintenance endpoints
• Scoped machine credentials for callback endpoints

Authorization model

Authentication alone is not sufficient. Handlers must also enforce organization ownership:

• Query by resource ID and organization ID together.
• Reject cross-org access with 403 responses.
• Enforce role gates at route boundaries. dashboard_only users are restricted to their mapped /app/org-dashboard/* routes and are denied /api/* access.

Error contract

Recommended auth response payload:

{
  "error": "unauthorized",
  "message": "Authentication required"
}

Use 401 for missing/invalid auth and 403 for authenticated-but-forbidden access.

Hardening checklist

• Validate payload shape with Zod before side effects.
• Keep secrets in environment variables only.
• Rotate API keys on compromise or operator turnover.
• Log auth failures with request context and no secret values.