logicspike/docs

Content Engine

Content Engine — API Gateway Integration Guide

This guide explains how to communicate with the Content Engine service through the centralized LogicSpike API Gateway.

Architecture Overview

The Content Engine (logicspike-content-engine) is an internal Cloudflare Worker that is NOT exposed directly to the public internet for client requests.

Instead, all external frontends and clients must send requests to the API Gateway (logicspike-gateway), which handles:

  1. Rate Limiting: Prevents abuse before requests hit the internal services.
  2. CORS: Only allows whitelisted frontends.
  3. Authentication: Validates JWT Bearer tokens to ensure the user is logged in.
  4. Access Control (PBAC): Verifies the user's tenant is subscribed to the content service entitlement.

Once access is granted, the Gateway silently forwards the request to the Content Engine via an internal, zero-latency Cloudflare Service Binding (CONTENT_ENGINE_SERVICE), injecting verified identity headers along the way.

Base URLs

  • Local Development Gateway: http://localhost:8788
  • Proxy Route Prefix: /content

To access the Content Engine's /slots endpoint, you send a request to the Gateway at /content/slots.

Authentication Required

Every request sent to the Gateway's /content/* routes MUST include a valid JSON Web Token (JWT).

In your HTTP Request, add the following header:

Authorization: Bearer <your-jwt-access-token>

Note: If the token is missing, expired, or invalid, the Gateway will return a 401 Unauthorized without ever waking up the Content Engine.

Internal Handshake (Automatic)

You only need to provide the JWT. The Gateway decodes your JWT and passes the trusted data to the Content Engine via internal HTTP headers. The Content Engine implicitly trusts these headers because they come from the Gateway binding (protected by x-gateway-key).

Headers automatically appended by the Gateway:

  • x-tenant-id: The ID of your workspace.
  • x-user-id: Your user ID.
  • x-user-permissions: Your array of PBAC permissions.
  • x-gateway-key: The internal shared secret.

Making a Test Request

Here is an example of fetching Content Slots via the API Gateway using curl:

curl -X GET http://localhost:8788/content/slots \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Steps to Test Locally:

  1. Ensure both the Gateway and the Content Engine workers are running. Usually, running pnpm run dev at the workspace root starts all services.
  2. Generate or obtain a valid access token (using the Auth service, or a script like apps/content-engine/test-gateway-auth.ts).
  3. Make requests to http://localhost:8788/content/... using tools like Postman, Bruno, or fetch in your frontend code!
Content Engine