Skip to content

Authentication

Authentication implementation and usage for the Microlearning Platform.

Guides

Authentication Guide

Overview of authentication:

  • Four-layer protection stack
  • JWT token handling and lifecycle
  • Role-based access control (RBAC)
  • User session management

Auth Implementation

Technical implementation details:

  • OAuth-based authentication (Google, GitHub)
  • Session management with secure cookies
  • Supabase Auth integration
  • Service-to-service authentication

Service-to-Service Guide

Service-to-service authentication:

  • Cloudflare Worker / SSR / ISR integration
  • X-Service-Auth header usage
  • SERVICE role permissions and access boundaries
  • Security considerations and troubleshooting

Authentication Methods

The API supports two authentication methods:

1. User JWT (Client Applications)

Client App ──► Supabase Auth ──► JWT Token ──► Edge Function ──► Protected Route

Used by browsers and mobile apps. The user signs in via Supabase Auth (OAuth or email/password), receives a JWT token, and includes it in the Authorization: Bearer <token> header.

2. Service Auth (Server-to-Server)

Cloudflare Worker ──► X-Service-Auth Header ──► Edge Function ──► SERVICE Context

Used by backend services (Cloudflare Workers, Next.js ISR/SSR). The service includes the shared secret in the X-Service-Auth header. No user JWT is needed.

Authentication Flow

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Client      │────►│   Supabase      │────►│   Edge          │
│   Application   │     │   Auth          │     │   Functions     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │  1. Login/Signup      │                       │
        │──────────────────────►│                       │
        │                       │                       │
        │  2. JWT Token         │                       │
        │◄──────────────────────│                       │
        │                       │                       │
        │  3. API Request + JWT                        │
        │─────────────────────────────────────────────►│
        │                       │                       │
        │                       │  4. Resolve Context   │
        │                       │◄─────────────────────│
        │                       │                       │
        │  5. Response                                 │
        │◄─────────────────────────────────────────────│


┌─────────────────┐                             ┌─────────────────┐
│  Cloudflare     │  X-Service-Auth: <secret>   │   Edge          │
│  Worker (ISR)   │────────────────────────────►│   Functions     │
└─────────────────┘  (no Authorization header)  └─────────────────┘

Endpoint Authentication

All API endpoints require authentication via one of the two methods above.

Method Header Use Case
User JWT Authorization: Bearer <token> Client applications
Service Auth X-Service-Auth: <secret> Server-to-server (ISR/SSR)

Endpoint Access Matrix

Endpoint User JWT Service Auth Notes
GET /graph/* Yes Yes Content browsing
GET /content/* Yes Yes Lesson content
GET /home Yes Yes Homepage aggregation
GET /journeys/* Yes Yes Journey catalog
GET /search/* Yes Yes Full-text search
GET /metadata/* Yes Yes Static enumerations
GET /snapshots/* Yes Yes Content versioning
GET /me/* Yes No Requires TRACK_PROGRESS
POST /me/events/* Yes No Requires TRACK_PROGRESS