🏗️ Architecture: How should SYSTEM_TOKEN and BACKEND_API_INTERNAL_TOKEN relat...

Date: 2026-02-10
Time: 17:02:07 UTC
Session: gspace1-102.7
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should SYSTEM_TOKEN and BACKEND_API_INTERNAL_TOKEN relate to each other for inter-service authentication?

Task: Railway environment variable audit - Session 102.3

🎯 Decision Made

Chosen:

SYSTEM_TOKEN and BACKEND_API_INTERNAL_TOKEN must have the SAME value. SYSTEM_TOKEN is read by receiving services' auth guards to validate incoming requests. BACKEND_API_INTERNAL_TOKEN is read by calling services (vitto-api, ai-api) to attach as Bearer token on outgoing HTTP calls. Both set to a strong 64-char hex token generated with crypto.randomBytes(32).toString('hex').

Options Considered:

1. Keep guessable token
2. Use different tokens per service pair
3. Single strong token shared across all services

💭 Reasoning

The old SYSTEM_TOKEN (gograb-system-internal-2024) was guessable and granted full system-level access bypassing JWT validation. A cryptographically random token eliminates guessability. SYSTEM_TOKEN must be on ALL 4 Railway services. BACKEND_API_INTERNAL_TOKEN only on services that make outgoing calls (vitto-api, ai-api). They must match because one is 'what I send' and the other is 'what I check against'.

📁 Files Involved

• libs/libs-api/backend-core/src/lib/config/cors.factory.ts
• apis/backend-vitto-api/src/app/connectivity/backend-ai-client.service.ts

🔗 Related

• Decision ID: dev_1770742923655_6pgviic
• Session: 102
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation