core-api-gateway

The single entry point for all client requests. Handles routing, authentication, organization resolution, rate limiting, caching, and security headers. Injects the X-Internal-Key and X-Organization-Id headers that downstream services rely on for trust and authorization.

Worker name: crow-core-api-gateway Domain (prod): api.crowai.dev Domain (dev): dev.api.crowai.dev

Routing

The gateway routes requests based on the path segment after /api/v{n}/:

Path Segment	Service Name	Internal URL (dev)
auth	core-auth-service	dev.internal.auth-api.crowai.dev
better-auth	core-auth-service	dev.internal.auth-api.crowai.dev
users	core-user-service	dev.internal.users.crowai.dev
products	core-product-service	dev.internal.products.crowai.dev
crawler-jobs	core-product-service	dev.internal.products.crowai.dev
organizations	core-organization-service	dev.internal.orgs.crowai.dev
analytics	core-analytics-service	dev.internal.analytics.crowai.dev
notifications	core-notification-service	dev.internal.notifications.crowai.dev
patterns	core-pattern-service	dev.internal.patterns.crowai.dev
interactions	core-interaction-service	dev.internal.interactions.crowai.dev
chat	bff-chat-service	dev.internal.chat.crowai.dev
qna	bff-qna-service	dev.internal.qna.crowai.dev
mcp	mcp-service	dev.mcp.crowai.dev
billing	core-billing-service	dev.internal.billing.crowai.dev
cctv	cctv-ingest-service	dev.cctv.crowai.dev

Middleware Pipeline

For authenticated service routes (/api/v{n}/{service}/*):

1. standardRateLimitMiddleware -- per-IP rate limiting
2. authenticateRequestMiddleware -- session cookie or API key validation
3. injectOrganizationContext -- resolves org UUID, sets context
4. cacheMiddleware -- KV-backed response cache
5. handleRequest -- forwards to internal service

For auth routes (/api/v{n}/auth/*):

1. authenticationRateLimitMiddleware -- stricter rate limiting
2. handleRequest -- forwards directly (no auth/org middleware)

Authentication Middleware

Three-tier token resolution:

1. Session cookie -- reads better-auth.session_token cookie, calls auth service GET /get-session for JWT token and org
2. API key -- detects crow_ prefix in X-API-Key, ApiKey header, or Bearer token; resolves via POST /api-key/verify
3. Anonymous -- for non-auth-required services, creates an anonymous session JWT cached per client IP in KV (1-hour TTL)

Organization Resolution Middleware

1. Session path: Calls GET /auth/get-session to get activeOrganizationId, then calls GET /organizations/by-auth-id/:id to resolve internal UUID
2. API key path: Gets org from API key metadata, then verifies user membership via GET /users/by-auth-id/:id
3. Strips client-supplied X-Organization-Id and X-User-Id headers before injecting gateway-resolved values

Cache Middleware

KV-backed response cache. Cache key includes the service name, API version, pathname, and organization ID to prevent cross-org data leakage:

cache:{service}:{version}:{pathname}:{orgId}

Request Forwarding

The forwardRequest function:

• Builds the target URL from the service config and environment
• Strips and re-injects X-Organization-Id, X-User-Id headers
• Injects X-Internal-Key from env.INTERNAL_GATEWAY_KEY
• Sets Authorization: Bearer <jwt> from the resolved token
• Does not forward crow_ API keys as Bearer tokens (downstream services reject non-JWTs)

Public Path Overrides

These paths bypass authentication even on requiresAuth services:

• POST /api/v{n}/billing/webhook -- Stripe webhook (signature-verified)
• GET /api/v{n}/{service}/health -- health probes
• GET /api/v{n}/{service}/ready -- readiness probes

Environment Variables

Variable	Example
ENVIRONMENT	dev
AUTH_SERVICE_URL	https://dev.auth.crowai.dev

Secrets

Secret	Purpose
INTERNAL_GATEWAY_KEY	Injected into all forwarded requests
SERVICE_API_KEY_ORG_SERVICE	Used for by-auth-id lookups on org and user services
CRAWLER_SERVICE_SECRET	Forwarded to product service for crawl auth

Bindings

Binding	Type	Name
CACHE	KV	Response cache + auth token cache

Dependencies

• Outbound: auth service (session validation, JWT retrieval, API key verification), org service (by-auth-id lookup), user service (API key org membership verification), all downstream services (request forwarding)
• Inbound: all clients (dashboard, auth-client, SDKs, MCP, API keys)

CORS

Allowed origins include all production and dev domains for the platform services and clients. Local development origins (localhost:3000-3002, localhost:8000-8012) are added when ENVIRONMENT=local.