Authentication
Overview of hookstream authentication methods — API keys and session cookies.
hookstream supports two authentication methods: API keys for programmatic access and session cookies for browser-based dashboard use. Most API endpoints use combined auth, accepting whichever succeeds first.
Authentication methods
API key authentication
Send your API key in the X-API-Key header. hookstream hashes the key with SHA-256 and looks up the hash in D1. Keys use the format hs_live_<64 hex> for production or hs_test_<64 hex> for test mode.
bashcurl -H "X-API-Key: hs_live_abc123..." https://hookstream.io/v1/sources
Create and manage API keys on the API Keys page.
Session authentication
The hookstream dashboard uses cookie-based sessions via Better Auth. When you sign in through the web UI (email/password or Google/GitHub OAuth), a session cookie is set automatically. All subsequent API requests from the browser include this cookie.
On first login, hookstream auto-provisions an organization and a default project for the user.
Combined auth
Most endpoints use combinedAuth middleware, which tries API key authentication first. If no X-API-Key header is present or the key is invalid, it falls back to session cookie verification. This allows both programmatic access and browser access on the same endpoint.
Frontend code uses credentials: "include" on fetch calls. There are no Bearer tokens — all auth is cookie-based in the browser and header-based from server code.
Public endpoints
Some endpoints require no authentication and use IP-based rate limiting instead:
/v1/ingest/:source_id— public webhook ingestion/v1/test/*— ephemeral test sessions/v1/tools/*— free developer tools/v1/health— service health check/v1/ws/test/:source_id— test session WebSocket