Gateway API

The gateway worker (worker-gateway) is the single entry point for all API requests. It handles session verification, request routing, and header injection for downstream workers.

Base URL

http://localhost:8787  (development)
https://api.example.com  (production)

Authentication

Most endpoints require a valid Better Auth session cookie (better-auth.session_token). The gateway verifies the session by calling worker-auth internally and injects user context headers before proxying.

Injected Headers

When a session is valid, the gateway adds these headers to downstream requests:

Header	Description
X-User-Id	Authenticated user’s ID
X-User-Role	User role (user or admin)
X-App-Key	Application key for multi-tenant isolation

Route Map

Public Routes (no session required)

Method	Path	Upstream	Description
*	/auth/*	worker-auth	Better Auth endpoints (sign-up, sign-in, etc.)
POST	/payment/webhook/*	worker-billing	Payment provider webhooks

Authenticated Routes

Method	Path	Upstream	Description
*	/credits/*	worker-billing	Credit balance and transactions
*	/checkin /checkin/*	worker-billing	Daily check-in
*	/orders /orders/*	worker-billing	Order history
*	/subscription/*	worker-billing	Subscription management
*	/payment/*	worker-billing	Payment session creation
*	/tickets /tickets/*	worker-support	Support tickets
*	/keys /keys/*	worker-ai	API key management
*	/user/*	worker-auth	User profile
*	/content/*	worker-content	Public content

Admin Routes (requires admin role)

Method	Path	Upstream	Description
*	/admin/billing/*	worker-billing	Billing administration
*	/admin/credits/*	worker-billing	Credit administration
*	/admin/checkin/*	worker-billing	Check-in configuration
*	/admin/ai/*	worker-ai	AI provider/model management
*	/admin/posts /admin/posts/*	worker-content	Blog post management
*	/admin/banners /admin/banners/*	worker-content	Banner management
*	/admin/friend-links /admin/friend-links/*	worker-content	Friend link management
*	/admin/*	worker-admin	Other admin operations

Error Responses

All API responses use a consistent format:

Success

{
  "ok": true,
  "data": { ... }
}

Error

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired session"
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid session
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Request body failed schema validation
INTERNAL_ERROR	500	Unexpected server error