Skip to main content
The Gateway API is a Cloudflare Worker that serves as the single entry point for all MetaCogna services. It handles authentication, routing, and request proxying to downstream workers.

​
Architecture

The Gateway API acts as a reverse proxy with JWT-based authentication, routing requests to specialized workers:

​
Key Features

JWT Authentication

Secure token-based authentication with SHA-256 credential hashing

Route Proxying

Intelligent routing to BUILD, KV, and CORE services

Error Handling

Unified error response format across all routes

Service Bindings

Secure inter-worker communication via Cloudflare service bindings

​
Routing Matrix

The gateway routes requests based on URL prefixes:

​
Quick Start

​
Installation

​
Development

​
Environment Setup

The gateway requires the following environment variables:
  • GATEWAY_JWT_SECRET - Secret key for JWT signing and verification
  • BUILD_SERVICE_URL - URL of the build service worker
  • KV_SERVICE_URL - URL of the KV service worker
  • CORE_SERVICE_URL - URL of the core service worker

​
R2 Bucket

The gateway uses an R2 bucket (metacogna-accounts) to store admin credentials:
  • Path format: auth/admins/{username}.json
  • Structure: { username, salt, hash, role }

​
Project Structure

​
How It Works

  1. Client Request: Client sends request to api.metacogna.ai/{path}
  2. Authentication: For protected routes, client includes Authorization: Bearer {token} header
  3. Route Matching: Gateway matches URL prefix to route configuration
  4. Token Verification: For protected routes, gateway verifies JWT token
  5. URL Rewriting: Gateway strips route prefix and forwards to target service
  6. Response Proxying: Gateway returns response from downstream service