🏗️ Architecture: How should API identity/explorer page authenticate users sec...

Date: 2026-02-09
Time: 19:44:11 UTC
Session: gspace1-101.5
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How should API identity/explorer page authenticate users securely?

Task: Not specified

🎯 Decision Made

Chosen:

Hybrid: static HTML + client-side JS fetch with Bearer JWT

Options Considered:

1. Raw shared secret in query param (current, insecure)
2. Cookie-based auth (first-party HttpOnly)
3. Hybrid: static HTML + client-side JS fetch with Bearer JWT
4. Full OAuth redirect flow like VSCode extension

💭 Reasoning

Uses existing JwtAuthGuard and SystemRoles without modifications. No tokens in URLs, no cookies (avoids CSRF complexity on stateless API), no new auth pathways. Server renders public HTML shell, inline JS handles auth via Authorization: Bearer header to a protected /api/system/explorer endpoint. Role-gated: DEVELOPER/ADMIN see route explorer, authenticated users see extra links, public sees minimal info. sessionStorage for tab-scoped token persistence.

📁 Files Involved

• libs/libs-api/backend-core/src/lib/utils/service-identity.utils.ts
• libs/libs-api/auth-core/src/lib/guards/jwt-auth.guard.ts
• apis/backend-api/src/app/app.controller.ts
• apis/backend-api/src/app/app.service.ts

🔗 Related

• Decision ID: dev_1770666251024_nx4ojpv
• Session: 101
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation