Authentication

API Key (server-to-server)

Used by the PHP backend and other internal services. The key is set via the API_KEY environment variable.

curl -H "X-API-Key: your-secret-key" https://api.example.com/api/deals/abc-123

All /api/deals/* routes require a valid API key. Requests without it or with an invalid key receive a 401 Unauthorized response.

JWT Bearer (client-side)

Used by the web application for authenticated user actions. Tokens are issued by Clerk.

curl -H "Authorization: Bearer eyJhbG..." https://api.example.com/api/protected/resource

Two middlewares share the work:

• The identity middleware runs on every route and never refuses a request. It verifies the Bearer with verifyToken from @workspace/auth/server and sets auth ({ userId, email }) on the request context, or null when the header is absent, malformed, invalid or expired.
• requireAuth guards the protected routers: it answers 401 Unauthorized when auth is null, then sets userId and userEmail. An optional X-BT-Impersonation header lets an admin act as another account; see Impersonation.

A public route reads auth without requiring it. A deal read with the API key, for instance, names the player behind a Bearer to decide who pays the serve, and reads as an anonymous player for any token that names no account.

Public routes

Some endpoints (e.g. form submissions) require no authentication. These are rate-limited and validated via request schemas instead.